Functional Overview

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:

  1. Bear in mind that the ADACHK utility can use large record buffer lengths when making nucleus calls to verify spanned Data Storage records or an index structure with many levels. If this is the case, the settings of your LU and NAB ADARUN parameters may need to be increased.
  2. ADACHK does not require the Adabas nucleus to be active.
  3. A pending autorestart condition is detected and reported since this can contribute to errors. Message CHK012W will typically be returned as soon as ADACHK detects the autorestart and the next error is encountered. Due to timing issues, it is possible that an error will be reported when we have not yet detected the pending autorestart and the CHK012I message will follow later. The nucleus status is only checked when an error is encountered since ADACHK does all the processing on its own and there is no need to call the nucleus unless there is an error.
  4. ADACHK checks the nucleus status each time an error is encountered to determine whether the nucleus status has changed.
  5. If the nucleus is restarted during the time that ADACHK is running, ADACHK will reestablish its communication with the nucleus when an error is detected and it attempts to confirm the error with the nucleus. Messages are written when ADACHK notices a nucleus status change.

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:


ADACHK Function Equivalences with Other Utility Functions

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  

Detailed Processing

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
  1. Read through each Data Storage record, extracting the ISN and the Data Storage RABN. Feed the ISN and RABN into the sorter.

  2. If a Data Storage record is a spanned record, assemble the spanned Data Storage record. Then extract the secondary ISNs and Data Storage RABNs and feed them into sorter.

  3. Read through the primary and secondary address converters and compare them against the sorted records from Data Storage.

  4. Report errors.

ACSCAN

Scan address converter for reusable ISNs.

DSCHECK
  1. Read through each Data Storage record, extracting the Data Storage RABN and DSST value from data. Feed them into the sorter.

  2. Read through the DSST and compare it against the sorted records from Data Storage.

  3. Report errors.

ICHECK
  1. Read through the index structure.

  2. Check the index structure.

VALIDATE
  1. Read through each Data Storage record, extracting the descriptors, descriptor values, and the ISN. Feed them into the sorter.

  2. Call the ADACHK ICHECK utility function.

  3. Read the NI structure ,comparing it against the sorted descriptor values.

  4. Report errors.

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.

ADACHK Statistics

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.

Spanned Record Considerations

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.

Cipher File Considerations

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.

Syntax Checking with 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 

Sort Data Set Considerations

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))

SORTTYPE=EXTERNAL Operating System Considerations

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.

z/OS

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:

  1. Modify the OPDOS member, specifying the name of the sort program in parameter SORTPGM.

  2. Modify and run member ASMLOPD to assemble and link the module ADAOPD.

ADACHK Print Function Output Format

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:

  1. 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.

  2. Section 2 shows GCB information for each RABN in the ADACHK run.

  3. 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.

graphics/assoprint_output.png

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.

Sample ADACHK Jobs

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:
  • ADACHK ICHECK: The ICHECK utility function is run for all database files.

  • ADACHK DSCHECK FILE=1,2: The DSCHECK utility function is run for files 1 and 2.

  • ADACHK DSCHECK FILE=17: The DSCHECK utility function is run for file 17.

  • ADACHK VALIDATE FILE=3: The VALIDATE utility function is run for file 3.

  • ADACHK ACCHECK: The ACCHECK utility function is run for all files.

  • ADACHK CHECK FILE=21: The CHECK utility function is run for file 21.

  • ADACHK FSTPRINT: The FSTPRINT utility function is run for the database.

  • ADACHK FCBPRINT FILE=1: The FCBPRINT utility function is run for file 1.