The ADACHK utility can be used to check the integrity of the entire database. All ADACHK utility functions can be run online with concurrent updates running.
You can use the ADACHK utility to:
Perform all integrity checks and print functions previously available using the ADAPRI, ADAACK, ADAICK, ADADCK and ADAVAL utilities.
Check the address converter against data storage (ADACHK ACCHECK utility function).
Check Data Storage and the Data Storage space table (DSST) (ADACHK DSCHECK utility function).
Check the physical structure of the index (ADACHK ICHECK utility function).
Validate any or all files within an Adabas database, except the checkpoint and security files (VALIDATE utility function).
Print or dump Associator blocks, command log blocks, Data Storage blocks, the File Control Block, the field definition table, the free space table, the general control block, the normal index, the upper index, protection log blocks, recovery log blocks, sort data set blocks, temporary data set blocks, and work data set blocks.
Scan address converter for a file or files and identify the ranges of unused (reusable ISNs) with the option to specify RESET to set the rotating AC ISN pointer to the first, largest range identified.
In addition, the ADACHK CHECK utility function performs a combination of the ACCHECK, DSCHECK, ICHECK, and VALIDATE utility functions as well as the gap and overlap checks provided in the ADAREP utility. A table showing the expanded file chains is also provided when LAYOUT=LONG.
This functionality was provided in releases of Adabas prior to 8.3 only by running the ADAACK, ADAICK, ADADCK, ADAVAL ADAPRI, and ADAREP utilities. The ADACHK utility executes all of these functions in one function, ADACHK CHECK, and can be run while concurrent updates are being performed against the file.
You can run ADACHK against the entire database, just one file, or a range of files. Processing occurs on a file by file basis rather than by processing multiple files in parallel. Processing multiple files at once may hinder performance, particularly during the sort functions.
In a single ADACHK run, database-wide checks, such as checks for expanded files, gaps, and overlaps, are performed only once regardless of how many functions are specified in the run (once per invocation when using the multifunction option). Such checks involve reading all of the file control blocks (FCBs) and would incur too much overhead if they were done for each individual function in the run. Before Adabas 8.3 introduced the ADACHK CHECK utility function, different utilities (ADAACK, ADADCK, ADAICK, and ADAVAL) were used to check the integrity of the entire database. Consequently, several reads of each database block were necessary to check the whole database. With ADACHK CHECK, each block is processed only once (except for rare occasions) thus greatly improving the performance of the integrity checks. Multiblock I/Os are also used whenever possible, also enhancing performance.
Anytime ADACHK reads a block it verifies the consistency of the block on its own and reports any inconsistencies that it detects. ADACHK has been designed in such a manner that each record (Data Storage, address converter, index) is only read once. This is a substantial performance improvement from the existing check utilities. A further performance enhancement is that ADACHK functions (including ADACHK VALIDATE) can check the entire database on their own, without making nucleus calls (the ADAVAL utility must make nucleus calls when it runs). It only makes nucleus calls if it encounters an error that may be transient (caused by a concurrent update), in which case ADACHK must confirm whether the block in question is currently being updated.
The ADACHK utility does not require that its SORT data set be preformatted and in z/OS environments, it can dynamically increase the size of the SORT data set. If a single SORT data set (DDSORTR1) is in use, ADACHK can dynamically extend it if it fills up. If two SORT data sets are in use (DDSORTR1 and DDSORTR2), ADACHK can dynamically extend the DDSORTR2 data set if it fills up. In addition, instead of using its own, internal sorter, ADACHK can also be configured to use an external sorter -- that is, the sorter (if any) provided by your installation -- by specifying SORTTYPE=EXTERNAL. In this configuration, DDSORTR1 and/or DDSORTR2 need not be specified and any sorter-related specifications must be done for the external sorter.
Notes:
The physical layout check of the entire database, including checks for overlaps, gaps, and the integrity of expanded file chains, is only performed for the check functions of ADACHK (ACCHECK, DSCHECK, ICHECK, CHECK, and VALIDATE). In addition, this check is performed only once per ADACHK execution, even if you are performing a multifunction run of the ADACHK utility running multiple check functions. Checking the physical layout of the database is an enhancement with ADACHK but produces a lot of overhead because this ADACHK processing requires that it read the FCB for every file in the database. Consequently, to maximize performance gains in ADACHK processing, the physical layout check is only performed once per ADACHK execution. Therefore, if an error exists related to the physical layout of the database (gaps, overlaps, expanded file chains), this error is only seen and reported for the first check function in the multifunction run.
The following example shows where the physical layout check is performed in a multifunction execution of ADACHK using the following statements:
ADACHK NIPRINT FILE=1 ADACHK GCBPRINT ADACHK ACCHECK <-----------Physical layout check is performed here before processing first file
Here is a second example showing where the physical layout check is performed if you are running a multifunction execution of ADACHK.
ADACHK ACCHECK FILE=1 <-----------Physical layout check is performed here ADACHK FCBPRINT FILE=2 ADACHK CHECK ADACHK DSCHECK FILE=95 ADACHK CHECK FILE=20
This document covers the following topics:
The following table matches ADACHK utility functions with the equivalent functions previously available with the ADAPRI, ADAACK, ADAICK, ADADCK and ADAVAL utilities. ADACHK utility functions can be run online with concurrent updates running.
Note:
The
LAYOUT=SHORT (the default) parameter setting is used for each of these ADACHK
functions to minimize output when all structures are correct. LAYOUT=LONG can
be used if the additional output is desired.
| ADACHK Utility Function | Equivalent Other Utility Function | Comments |
|---|---|---|
| ACCHECK | ADAACK ACCHECK ADAICK ACCHECK |
ACCHECK can also be run online while concurrent updates are running. This utility function includes expanded file chain and gap/overlap checks similar to those provided by the ADAREP utility. |
| ACSCAN | none | --- |
| ASSOPRINT | ADAICK ASSOPRINT ADAPRI ASSOPRI |
The results from the ADACHK ASSOPRINT LAYOUT=LONG setting are what you get when you run the equivalent ADAICK or ADAPRI utility function. |
| CHECK | none | The CHECK utility function performs a combination of the ACCHECK, DSCHECK, ICHECK, and a VALIDATE utility functions as well as the gap and overlap checks provided in the ADAREP utility. CHECK can also be run online while concurrent updates are running. |
| CLOGPRINT | ADAPRI CLOGPRI | |
| DATAPRINT | ADAICK DATAPRINT ADAPRI DATAPRI |
The results from the ADACHK DATAPRINT LAYOUT=LONG setting are what you get when you run the equivalent ADAICK or ADAPRI utility function. |
| DSCHECK | ADADCK DSCHECK ADAICK DSCHECK |
DSCHECK can also be run online while concurrent updates are running. This utility function includes expanded file chain and gap/overlap checks similar to those provided by the ADAREP utility. |
| DSIMPRINT | ADAPRI DSIMPRI | |
| DSSTPRINT | none | --- |
| FCBPRINT | ADAICK FCBPRINT ADAPRI |
The results from the ADACHK FCBPRINT LAYOUT=LONG setting are what you get when you run the equivalent ADAICK or ADAPRI utility function. |
| FDTPRINT | ADAICK FDTPRINT ADAPRI |
The results from the ADACHK FDTPRINT LAYOUT=LONG setting are what you get when you run the equivalent ADAICK or ADAPRI utility function. |
| FSTPRINT | none | --- |
| GCBPRINT | ADAICK GCBPRINT ADAPRI |
The results from the ADACHK GCBPRINT LAYOUT=LONG setting are what you get when you run the equivalent ADAICK or ADAPRI utility function. |
| ICHECK | ADAICK ICHECK | ICHECK can also be run online while concurrent updates are running. This utility function includes expanded file chain and gap/overlap checks similar to those provided by the ADAREP utility. |
| NIPRINT | ADAICK NIPRINT ADAPRI |
The results from the ADACHK NIPRINT LAYOUT=LONG setting are what you get when you run the equivalent ADAICK or ADAPRI utility function. |
| PLOGPRINT | ADAPRI PLOGPRI | |
| PPTPRINT | ADAICK PPTPRINT ADAPRI |
The results from the ADACHK PPTPRINT LAYOUT=LONG setting are what you get when you run the equivalent ADAICK or ADAPRI utility function. |
| RLOGPRINT | ADAPRI RLOGPRI | |
| SORTPRINT | ADAPRI SORTPRI | |
| TEMPPRINT | ADAPRI TEMPPRI | |
| UIPRINT | ADAICK UIPRINT ADAPRI |
The results from the ADACHK UIPRINT LAYOUT=LONG setting are what you get when you run the equivalent ADAICK or ADAPRI utility function. |
| VALIDATE | ADAVAL VALIDATE | VALIDATE can also be run online while concurrent updates are running. This utility function includes expanded file chain and gap/overlap checks similar to those provided by the ADAREP utility. |
| WORKPRINT | ADAPRI WORKPRI |
Anytime ADACHK reads a block, it verifies the consistency of the block on its own and reports any inconsistencies that it detects. Data structures involving more than one block are more challenging to check in an efficient manner.
Each block (Data Storage, address converter, indices) is only read once in an ADACHK run. As Data Storage blocks are read, depending on the function being requested, parts of each record are extracted and fed into the sorter for comparison with data from other blocks at a later point in time. The information from Data Storage is extracted first. Therefore, when an inconsistency with the address converter, index, or DSST is discovered, the entire Data Storage record is no longer available to ADACHK; only the portion of the record that was extracted for sort purposes is available. The information in the sorter may not always reflect the current status if there have been concurrent updates. For example, any records that have been added by users since the start of the ADACHK run will not be in the sorted output. Similarly, any items that were deleted by users since the start of the ADACHK run will be in the sorted records but will not be contained in the database. When this happens, verification calls to the nucleus are made. If ADACHK is not able to ascertain for sure if there is an inconsistency, the nucleus is called to verify if the error is real or transient. When multiple blocks are involved and parallel updates are occurring, before ADACHK can report an error as real, a call is made to the nucleus for a fresh copy of the blocks involved to verify if the error is real or transient. This allows concurrent updating to take place on the files while the consistency checks are running.
In more detail, the following is a high-level overview of the processing that occurs for each ADACHK function:
| ADACHK Function | Processing |
|---|---|
| ACCHECK |
|
| ACSCAN |
Scan address converter for reusable ISNs. |
| DSCHECK |
|
| ICHECK |
|
| VALIDATE |
|
| CHECK | Processing for CHECK is a combination of processing for the ACCHECK, DSCHECK, ICHECK and VALIDATE utility functions. |
The sort input phase runs first in all functions, except the ADACHK ICHECK utility function, where the sorter is not invoked. This allows ADACHK to read each component only once. Sorting all extracted data in one large operation also eliminates the need to have a temporary data set to store the data. It does however slightly increase the likelihood of concurrent updates not captured in the sorted data. Therefore, in the event that ADACHK encounters an error, it must determine whether the error may be due to concurrent updates and, if necessary, check with the nucleus.
With the previously supported Adabas integrity checking utilities (ADAACK, ADAICK, ADADCK and ADAVAL), several reads of each block were necessary to check the integrity of the entire database. With ADACHK CHECK, each block is processed only once (except for rare occasions), thus greatly improving the performance of integrity checks. Multiblock I/Os are also used whenever possible to enhance performance. ADACHK functions (including ADACHK VALIDATE) can also check the entire database on their own, without making nucleus calls. This is accomplished by reading compressed records from Data Storage and creating a DVT that is validated against each corresponding value in the indices. ADACHK only makes nucleus calls if it encounters an error that could be due to concurrent updates, in which case it must confirm whether the block in question is currently being updated.
The following are statistics normally printed at the end of each function, one set per database file.
<ADACHK> Nucleus Statistics - Error Verifications Number of transient errors = nn Number of nucleus verification calls = nn Number of nucleus retries = nn Number of AC blocks returned from nucleus = nn Number of Index blocks returned from nucleus = nn Number of Data blocks returned from nucleus = nn Number of nucleus status changes = nn Number of Buffer flushes = nn
If the REPAIR option of the ADACHK DSCHECK utility function is run, the following additional statistics are printed:
Number of repairs attempted = nn Number of repairs completed = nn
The statistics provide information on how much interaction took place with the nucleus during the ADACHK processing. These can help aid in performance tuning if heavy updating is occurring at the same time ADACHK is running. These same statistics can be displayed at any point during ADACHK processing by issuing the DSTAT command against the ADACHK job. In addition to these statistics, information is displayed on ADACHK processing progress, including identifying the file ADACHK is currently processing. The statistics displayed for the operator command DSTAT are the same as these ADACHK statistics with the exception that only statistics for the file currently being processed are displayed along with the function in progress.
If NOSYNC, UTYPE=EXU or UTYPE= EXF are specified in an ADACHK run, no nucleus calls are made and the statistics are suppressed.
The following table describes the statistics in more detail:
| Statistics | Description |
|---|---|
| Number of transient errors | A transient error is an error that ADACHK detected and determined was due to a concurrent update in progress. A transient error can be determined in some cases without the help of the nucleus by rereading the block in question. When this number is higher than the number of nucleus verification calls, you know that ADACHK resolved one or more transient errors on its own. Every error encountered goes through the transient error verification process. Even if the nucleus was down when ADACHK started, the nucleus could have been restarted and therefore ADACHK attempts to call the nucleus unless instructed by parameters that indicate not to do so (UTYPE, NOSYNC, and MAXCALLS parameters). |
| Number of nucleus verification calls | The number of calls made from ADACHK to the nucleus to verify if an error was real or transient. |
| Number of nucleus retries | The number of retries the nucleus performed due to concurrent updates. |
| Number of AC blocks returned from nucleus | The number of address converter blocks returned from the nucleus to ADACHK. ADACHK stores these newly read blocks in its storage in an effort to reduce further nucleus calls. |
| Number of Index blocks returned from nucleus | The number of index blocks returned from the nucleus to ADACHK. ADACHK stores these newly read blocks in its storage in an effort to reduce further nucleus calls. ADACHK and the nucleus track which blocks have previously been returned and, if ADACHK already has the same copy of the block and it has not been updated, the nucleus will not return the block again in an effort to maximize performance. |
| Number of Data blocks returned from nucleus | The number of Data Storage blocks returned from the nucleus to ADACHK. ADACHK stores these newly read blocks in its storage in an effort to reduce further nucleus calls. |
| Number of nucleus status changes | The number of times the nucleus changed its status (for example, from active to inactive). |
| Number of Buffer flushes | The number of buffer flushes requested by ADACHK. |
| Number of repairs attempted | If the REPAIR option is specified for the ADACHK DSCHECK utility function, this statistic shows the number of repairs attempted for the run. |
| Number of repairs completed | If the REPAIR option is specified for the ADACHK DSCHECK utility function, this statistic shows the number of repairs completed for the run. |
ADACHK can use large record buffer lengths when making nucleus calls to verify spanned Data Storage records. If this is the case, you may need to increase the settings of your LU and NAB ADARUN parameters.
In addition, bear in mind that integrity checks are done on spanned Data Storage RABNs as they are being assembled and also later, depending on what ADACHK function is running. Therefore, you may see a particular error message more than once during ADACHK processing. For example, it is possible, when running the ADACHK CHECK function, that the ACCHECK portion of the CHECK run may identify an error that is also identified in the DSCHECK portion of the CHECK run.
If your database contains cipher files, you cannot run the ADACHK CHECK or ADACHK DSCHECK utility functions on the entire database in a single run. In addition, you can only run these functions on a single cipher file in one run and on the other (non-cipher) files by listing them specifically in the FILE parameter of another run.
Be sure to include the following parameters:
Specify the cipher key in the CODE parameter.
Specify a single cipher file in the FILE parameter.
If you do not specify both of these parameters, errors will result.
Note:
The TEST parameter does not check the types of files in the
database. This means that the TEST run will not show any ADACHK errors related
to cipher files in the run; these errors will only become apparent when you
perform the ADACHK run without the TEST parameter.
The ADACHK functions include a syntax-checking-only mode. When the TEST parameter is specified, the ADACHK function syntax is checked, but the function is not performed.
Note:
The TEST parameter does not check the types of files in the
database. This means that the TEST run will not show any ADACHK errors related
to cipher files in the run; these errors will only become apparent when you
perform the ADACHK run without the TEST parameter. This is particularly
pertinent for the ADACHK CHECK and DSCHECK utility functions.
ADACHK ACCHECK TEST
The sort data sets (DDSORTR1/DDSORTR2) need only be specified in a run when:
The ADACHK SORTPRINT utility function is run; or
The ADACHK ACCHECK, CHECK, DSCHECK, and VALIDATE utility functions are run with parameter SORTTYPE=INTERNAL specified (this is the default) and when the amount of data to be sorted exceeds the space declared by the LWP parameter in these utility function runs.
To perform sorting when the amount of data to be sorted exceeds the space declared by the LWP parameter and the internal sorter (SORTTYPE=INTERNAL) is being used, one or two sort data sets defined in the ADACHK job may be used as temporary storage.
The VALIDATE function determines the length of their sort keys by the longest descriptor in the file or MAXDESCLEN plus the static part of the sort key (10 bytes). The number of sort records is determined by the number of values for the descriptors.
For DSCHECK and ACCHECK, the number of SORT records is based off of the number of records in the file and the length of these keys is shorter (10 bytes).
CHECK is a combination of all the functions so of course uses a combination of all the SORT records.
The sort data set(s) should be at least as large as the combined ASSO and DATA extents of the largest file to be processed by ADACHK.
The sort data sets are denoted by their symbolic/link names DDSORTR1 and DDSORTR2 in the ADACHK job. There is no need to format the sort data sets using the Adabas ADAFRM utility; even temporary files may be used.
The sort data sets will initially be allocated in the size of the primary allocator. When this space is exhausted, the last sort data set will be extended by the size of the secondary allocator. Whether an extension is possible depends on the underlying operating system; for example, it is not supported in z/VSE environments. The number of possible extensions depends on the underlying operating system and the type of the sort data sets.
The following sample z/OS job statement defines a sort data set that will initially be allocated as 100 cylinders and that can be extended by 500 additional cylinders.
//DDSORTR1 DD DSN=&&MYSORTR1,DISP=NEW,SPACE=(CYL,(100,500))
When the ADACHK parameter SORTTYPE=EXTERNAL is specified, the ADACHK utility uses a standard sort function installed in the operating system. The following additional considerations should be taken into account for each operating system.
No additional job steps are required by ADACHK when the sort function is invoked. However, depending on the amount of data to be sorted, the ADACHK job step may require additional sort-related DD statements for work files or for other sort-specific facilities. Refer to your system's sort documentation for more details.
Note:
A sort package generally supplies summary information when a
SYSOUT DD statement is specified.
When ADACHK invokes sort, by default it expects to transfer control to a load module named "SORT". If the sort module has a different name, you must reassemble and link the Adabas options module ADAOPD, specifying the name of the external sort program as follows:
Modify the OPDOS member, specifying the name of the sort program in parameter SORTPGM.
Modify and run member ASMLOPD to assemble and link the module ADAOPD.
The output produced by the ADACHK print functions (ASSOPRINT, CLOGPRINT, DATAPRINT, DSIMPRINT, DSSTPRINT, FCBPRINT, FDTPRINT, FSTPRINT, GCBPRINT, NIPRINT, PLOGPRINT, PPTPRINT, RLOGPRINT, SORTPRINT, TEMPPRINT, UIPRINT, and WORKPRINT) has three sections:
Section 1 is a general section, showing the ADACHK print function settings and the RABN ranges of the ASSO, DATA, WORK, and DSST sections of the database.
Section 2 shows GCB information for each RABN in the ADACHK run.
Section 3 shows the dumped blocks for each RABN in the ADACHK run.
The following example depicts these sections in a very simple (only one RABN) ADACHK ASSOPRINT run.
Depending on the setting of the LAYOUT parameter, two or more sections are printed.
If you specify LAYOUT=SHORT, sections 1 and 2 are printed.
If you specify LAYOUT=MEDIUM, sections 1 and 3 are printed.
If you specify LAYOUT=LONG, all three sections are printed.
The following sample ADACHK jobs are provided with your Adabas installation in the ADAvrs.JOBS (z/OS or BS2000) or ADAvrs.LIBR (z/VSE) library. You will need to tailor the jobs to direct them to your database and database files before you run them:
| Sample Job Name | Description |
|---|---|
| ADACHKC | This sample job checks the entire database for every possible ADACHK function. This is the equivalent of running the ADACHK ACCHECK, DSCHECK, ICHECK, and VALIDATE functions on every file. In addition, the entire database is checked for gaps and overlaps. |
| ADACHKP | This sample job runs multiple ADACHK print functions, including GCBPRINT, PPTPRINT, ASSOPRINT and DATAPRINT showing an example of one RABN or multiple RABNs. |
| ADACHKS | This sample job executes the ADACHK CHECK function using sort data sets. |
| ADACHKV | This sample job runs multiple ADACHK
print and check functions, as follows:
|