VERINDEX (Verify Index)

The VERINDEX (Verify Index) function is used to ensure the integrity of the dat data rows and their corresponding keys in the index.
datacom150
The VERINDEX (Verify Index) function is used to ensure the integrity of the
Datacom
data rows and their corresponding keys in the index.
When to Use VERINDEX
This function is designed to be used when you question the integrity of the index with the data, but the table cannot be taken offline. VERINDEX executes while the table is open for processing.
The function is intended to pass through the data and index areas producing a list of the index and data mismatches. You can review the output listing to make a determination of the action to be taken next. If there is only one index and data mismatch, you can attempt to fix it manually by deleting and adding a row again rather than rebuilding the entire index.
How to Use VERINDEX
Use the following format for this function:
►►─ VERINDEX DBID=
databaseid,
 ─ OPTION= ─┬─ DATAINDEX ─┬,─ TABLE=
tablename,
───►                                          └─ INDEXDATA ─┘  ►─┬──────────────────────────┬───────────────────────────────────────────────►◄    └─ KEYNAME= ─┬─ ALL ◄ ───┬─┘                 └─ keyname ─┘
Command
  • VERINDEX
    Invokes the function to verify the integrity of the index and data.
Required Keywords
  • DBID=
    Specifies the ID of the database.
    • Valid Entries:
      database ID
    • Default Value:
      (No default)
  • OPTION=
    Specifies the Option entry.
    • Valid Entries:
      DATAINDEX or INDEXDATA
    • Default Value:
      (No default)
  • TABLE=
    Specifies the three-character name of the table.
    • Valid Entries:
      table name
    • Default Value:
      (No default)
Optional Keyword
  • KEYNAME=
    Specifies the five-character name of the key in the table, if only one key in the table is to be verified. Omit the keyword to process all keys for the table.
    • Valid Entries:
      key name
    • Default Value:
      ALL
Data to Index (DATAINDEX)
The DATAINDEX option processes each data row for updating using physical data row order GSETP/GETPS commands with row locking. Once a data row is retrieved, the key definition information is used to construct the key value that should be in the index. The LOCKI (locate key intersection) command is issued to determine if there is an index entry with this key value that points to the data row. The process is repeated for each of the key definitions.
If an index entry is missing and an error message is produced, the processing then continues to the next key definition or data row. For any error, a flag is set so that at the end of the function execution a condition code is recognized.
The error message provides information about the record found and the key value that should exist but does not.
If an unexpected error occurs after a request, a system or program failure has occurred and the function terminates normally to DBUTLTY.
Once all data rows and their index entries have been processed, a final status message is produced which includes the data row counts, index entry counts, index error counts, and total I/O counts.
The process locks the data rows one at a time. The lock lasts until the index verifications are done. After the indexes are verified, the data row is unlocked and processing moves on to the next data row.
During this process, no errors are expected. If other tasks are performing maintenance concurrent with this process, it is possible for another task to UPDAT a record that is compressed in a manner that could move it from a block to the right of the task of the current physical block being processed to the left of the current block. In this event, it is possible for the data to index process to overlook this record and not verify its index values. This occurrence, however, is very rare.
A key can be defined in
Datacom Datadictionary
with the attribute INCLUDE-NIL-KEY that can be set to NO, where key values that are completely blanks or completely binary zeros are excluded from the index and are therefore not available for checking. This means that a key with INCLUDE-NIL-KEY that is all blanks or binary zeros is not checked or counted. This option is not available for the native sequence key nor the Master Key. This condition creates the possibility that counts of various keys might be different.
Sample Report
Following is a sample report page. For an example report header, see Sample Report Headers.
Sample Report DATAINDEX without an Error
 KEY RELATED STATISTICS:  KEYID   KEYNAME   MAST   MATCH_COUNT   ERROR_COUNT   STATUS      1     TST01      Y         21999             0   LD      2     TST02      N         21999             0   LD      3     TST03      N         21999             0   LD      4     TST04      N         21999             0   LD      5     TST05      N         21999             0   LD      6     TST06      N         21999             0   LD      7     TST07      N         21999             0   LD      8     TST08      N         21999             0   LD      9     TST09      N         21999             0   LD     10     TST10      N             0             0   NL AD  FINAL STATISTICS:    INDEX MATCHES        197991    INDEX ERRORS              0    I/O OPERATIONS        64524    ROWS PROCESSED        21999
This page of the report shows the DATAINDEX function without an error.
Sample Report DATAINDEX with an Error
 KEY TST02 NO INDEX FOUND, INDEX VALUE BELOW IN SYSUDUMP FORMAT, URI 00004478 DATA TTTR 00000106  00000000 TSN 00001111  C2875E07 BE0F7C83                                              *Bg [email protected]
This page of the report shows the DATAINDEX function with an error.
Index to Data (INDEXDATA)
The INDEXDATA option processes each key definition selected for the table. For each key definition, all index values are processed.
The index uses locate commands, LOCKG/LOCNX for processing. For each index entry, the matching data row is retrieved using a REDLE command. REDLE commands offer no exclusive control or protection from other concurrent tasks performing maintenance to the same table. If other tasks are not blocked from maintenance, many false errors can occur and must be handled or verified in some other way outside the scope of this DBUTLTY function. A data row not found is considered in doubt and an error message is generated. The processing then continues to the next index entry.
An unexpected return code indicates a system or program failure and causes the DBUTLTY function to terminate with the failure.
If a doubtful index condition occurs, a flag is set and at the end of the function, a normal DBUTLTY error is set.
Once the key definitions, their index entries, and their matching data rows have been processed, a final report is printed with details of the function.
The function does not lock the data rows. When an attempt is made to retrieve the data row and a RC=04 or RC=12 occurs, this means that the data row is not present at the time but could have been present when the index entry was retrieved. Errors in this case are considered in doubt.
To be sure the index and data are stable and that errors are real, perform the ACCESS=NOMAINT function on the DBID. This prevents any deletions and protects the LOCKG/REDLE processing. If the table must remain open to other users, do not restrict access and simply run the VERINDEX function. If errors are detected, run the same key name a second time. Key values that are errors on both runs would likely be true errors.
A key can be defined in
Datacom Datadictionary
with the attribute INCLUDE-NIL-KEY that can be set to NO, where key values that are completely blanks or completely binary zeros are excluded from the index and are therefore not available for checking. This means that a key with INCLUDE-NIL-KEY that is all blanks or binary zeros is not in the index and therefore cannot be used for comparison against the data. This option is not available for the native sequence key nor the Master Key. This condition creates the possibility that counts of various keys might be different.
Sample Report
Following is a sample report page. For an example report header, see Sample Report Headers.
DDB--Sample Report INDEXDATA (15.0)
 FUNCTION=VERINDEX                         DBID=00997                         OPTION=INDEXDATA                         TABLE=K01    KEY RELATED STATISTICS:  KEYID   KEYNAME   MAST   MATCH_COUNT   ERROR_COUNT   STATUS      1     TST01      Y         21999             1   LD      2     TST02      N         21999             1   LD      3     TST03      N         21999             1   LD      4     TST04      N         21999             1   LD      5     TST05      N         21999             1   LD      6     TST06      N         21999             1   LD      7     TST07      N         21999             1   LD      8     TST08      N         21999             1   LD      9     TST09      N         21999             1   LD     10     TST10      N             0             1   NL AD  FINAL STATISTICS:    INDEX MATCHES        197991    INDEX ERRORS              9    I/O OPERATIONS        65688                      DB10045E - ABNORMAL TERMINATION DUE TO ERROR(S)
This page of the report shows the following under KEY RELATED STATISTICS:
  • KEYID
    Displays the identification number of key.
  • KEYNAME
    Displays the name of key.
  • MAST
    Identifies whether the key is a Master Key.
  • MATCH_COUNT
    Displays the count of index entry key values found that matched data record key values.
    Keys that are in the process of being added or deleted have a STATUS of NL AD (not loaded adding) or NL DL (not loaded deleting). A key that is in the process of being added or deleted is reported with a MATCH_COUNT of 0 and is effectively skipped.
  • ERROR_COUNT
    Displays the count of the index entries that are in doubt. For each of the in doubt index values, a message and a dump of the key value are provided in the SYSOUT data set INDOUBT. The following section displays an example of this output.
  • STATUS
    Shows the status of an individual key, listing the same values as a CXX report lists for the key. Most keys have a status of LD for loaded, but keys that are in the process of being added or deleted have a STATUS of NL AD (not loaded adding) or NL DL (not loaded deleting). A key that is in the process of being added or deleted is reported with a MATCH_COUNT of 0 and is effectively skipped.
Example Dump INDOUBT Index Entries
For each of the index values that are in doubt, a message and a dump of the key value are provided in the SYSOUT data set INDOUBT.
 KEY TST01 NO RECORD FOUND, INDEX VALUE BELOW IN SYSUDUMP FORMAT, URI 0001E997 DATA TTTR 00004103  00000000  F0F5F4F2 F9F3F9F6                                                          *05429396                        *  KEY TST02 NO RECORD FOUND, INDEX VALUE BELOW IN SYSUDUMP FORMAT, URI 0001E997 DATA TTTR 00004103  00000000  C28EBF77 49D8F401                                                           *B....Q4.  KEY TST03 NO RECORD FOUND, INDEX VALUE BELOW IN SYSUDUMP FORMAT, URI 0001E997 DATA TTTR 00004103  00000000  F8F0F5F3 F6F2F8F8                                                           *80536288                        *  KEY TST04 NO RECORD FOUND, INDEX VALUE BELOW IN SYSUDUMP FORMAT, URI 0001E997 DATA TTTR 00004103  00000000  F0F0F0F0 F7F5F7F5                                                           *00007575                        *  KEY TST05 NO RECORD FOUND, INDEX VALUE BELOW IN SYSUDUMP FORMAT, URI 0001E997 DATA TTTR 00004103  00000000  C28EBF77 49D8F401                                                           *B....Q4.                        *  KEY TST06 ROW INDEX MISMATCH, INDEX VALUE BELOW IN SYSUDUMP FORMAT, URI 0001E997 DATA TTTR 00004103 TSN 00001111  00000000  00000000 00000000                                                           *........                        *  KEY TST07 NO RECORD FOUND, INDEX VALUE BELOW IN SYSUDUMP FORMAT, URI 0001E997 DATA TTTR 00004103  00000000  40404040 40404040 40404040 40404040   40404040 40404040                     *                                *  KEY TST08 NO RECORD FOUND, INDEX VALUE BELOW IN SYSUDUMP FORMAT, URI 0001E997 DATA TTTR 00004103  00000000  F9F9F9F9 F2F4F2F4                                                           *99992424                        *  KEY TST09 NO RECORD FOUND, INDEX VALUE BELOW IN SYSUDUMP FORMAT, URI 0001E997 DATA TTTR 00004103  00000000  F2F4F3F3 F6F6F1F4 F8F0F5F3 F6F2F8F8   F0F5F4F2 F9F3F9F6 F0F0F0F0 F7F5F7F5   *24336614805362880542939600007575*  00000020  C28EBF77 49D8F401 00000000 00000000   F9F9F9F9 F2F4F2F4 40404040 40404040   *B....Q4.........99992424        *  00000040  40404040 40404040 40404040 40404040   D2F0F140                              *                K01             *
The message provides the key name being processed with the URI value and the data block pointer in TTTR (track and record on track) format. The format is like a SYSUDUMP with the memory address in the first 8 positions, the hexadecimal formatted value, and the translation on the right.
If not found, the INDOUBT SYSOUT is dynamically allocated. It appears as //INDOUBT DD SYSOUT=*. If many errors are expected, as in a very large controlled test of mismatching data and index, the size can be limited with the OUTLIM option set: OUTLIM=999999.
The INDOUBT SYSOUT prints up to the first 180 bytes of each in-doubt key value.