IDCAMS EXAMINE

The IDCAMS EXAMINE command checks the structural consistency of a key-sequenced data set (KSDS) cluster. It tests both the index component and the data component for corruption, bad pointers, and inconsistencies. Unlike VERIFY, which corrects catalog and end-of-data information after abnormal termination, EXAMINE only diagnoses: it reads the cluster, runs integrity checks, and reports what it finds via condition codes and IDC messages on SYSPRINT. You use EXAMINE when you suspect a KSDS is damaged (e.g. after abends or open failures) and need to know whether the cluster is sound or needs recovery. This page explains EXAMINE syntax, INDEXTEST and DATATEST, condition codes 0/4/8, ERRORLIMIT, and how to use EXAMINE together with VERIFY RECOVER.

What EXAMINE Does

EXAMINE reads the KSDS cluster you name and runs a set of checks on the index and data components. For the index, it validates that the B-tree structure is consistent: vertical and horizontal pointers in index control intervals point to valid nodes, and the index information matches the layout of the data. For the data component, it reads every data control interval (including free space), checks record and CI integrity, free space accounting, spanned record capacity, and the internal VSAM pointers inside each CI. If it finds problems, it writes diagnostic messages (e.g. IDCxxxxx) to SYSPRINT and returns a condition code. EXAMINE does not alter the dataset; it only reports. So EXAMINE answers the question: "Is this KSDS structurally OK, or is it corrupted and in need of recovery?"

When to Use EXAMINE

Use EXAMINE when: (1) A program abends (e.g. 0C4) when accessing a KSDS and you want to confirm whether the cluster is damaged. (2) VERIFY has been run but you still get open or read errors, and you need to see if there is structural damage. (3) You are about to run a critical job and want to confirm the cluster is healthy. (4) You have restored a cluster from backup and want to verify its integrity before use. Do not use EXAMINE for ESDS, RRDS, or LDS; it is intended for KSDS (and in some environments, alternate index structures). For catalog or end-of-data correction, use VERIFY (and RECOVER); EXAMINE is for diagnosis only.

Syntax and Parameters

You specify the cluster by name and choose which tests to run. Typical form:

1
2
3
4
5
  EXAMINE -
    NAME(vsam-ksds-name) -
    [ INDEXTEST ] [ DATATEST ] -
    [ ERRORLIMIT(number) ]
 

NAME(vsam-ksds-name) is the full catalog name of the KSDS cluster. INDEXTEST and DATATEST are the two test types; you can specify one or both. Running both is recommended so that index and data are checked together—running only one can sometimes produce false condition code 8 due to orphaned index CIs that do not affect normal use. ERRORLIMIT(number) caps how many errors are reported (e.g. ERRORLIMIT(50)); after that, EXAMINE may stop reporting further errors but still complete the test. Omission of ERRORLIMIT may allow a very long listing if the cluster has many issues.

INDEXTEST and DATATEST

INDEXTEST and DATATEST are the two kinds of checks EXAMINE can perform. Each targets a different part of the cluster.

INDEXTEST is often the default if you do not specify DATATEST; the exact default can depend on your IDCAMS release. Running both INDEXTEST and DATATEST gives a full picture. If you run only INDEXTEST, you might see errors that are really due to unused or orphaned index CIs that do not affect normal keyed access; running DATATEST as well helps confirm whether the data is consistent with the index. So in practice, specify both unless your procedure says otherwise.

Condition Codes: 0, 4, and 8

EXAMINE returns a condition code (and the job MAXCC) to summarize the result. Interpretation can vary slightly by release; the following is the common meaning.

Code 0 means you can use the cluster. Code 4 means the cluster is still considered structurally sound but EXAMINE found some inconsistencies; check the IDC messages to see what they are and follow your site's guidelines. Code 8 means the cluster is corrupted; run VERIFY with RECOVER to fix catalog and end-of-data, then run EXAMINE again. If you still get 8 after VERIFY RECOVER, you may need to restore the cluster from backup (e.g. IMPORT or REPRO from a known-good copy) and then run VERIFY and EXAMINE.

ERRORLIMIT

ERRORLIMIT(number) limits how many error messages EXAMINE writes to SYSPRINT. For example, ERRORLIMIT(50) means EXAMINE will report up to 50 errors and then may stop adding more messages (or continue with a summary, depending on implementation). This keeps the listing from becoming huge when the cluster has many problems. If you omit ERRORLIMIT, all errors may be listed. Use a value that gives you enough detail without flooding the spool; 50 or 100 is often sufficient for diagnosis.

Example: Full Integrity Check

1
2
3
4
5
6
7
8
//EXAM     EXEC PGM=IDCAMS
//SYSPRINT DD   SYSOUT=*
//SYSIN    DD   *
  EXAMINE NAME(MY.APPL.CUSTOMER.KSDS) -
    INDEXTEST DATATEST -
    ERRORLIMIT(50)
/*
 

This runs both index and data tests on the cluster MY.APPL.CUSTOMER.KSDS and reports up to 50 errors. Check the job condition code: 0 means OK, 4 means OK with minor inconsistencies, 8 means corrupted. Read the SYSPRINT output for IDC messages that describe what was found.

EXAMINE and VERIFY Together

After abnormal termination, the usual sequence is: (1) Run VERIFY (and VERIFY RECOVER if the dataset was left inconsistent) to correct the catalog and high-used RBA. (2) Run EXAMINE to see if the cluster is structurally sound. If EXAMINE returns 0 or 4, the cluster is generally usable. If it returns 8, VERIFY RECOVER may have fixed catalog issues but structural damage may remain; review the IDC messages and consider restore from backup. So VERIFY fixes catalog/end-of-data; EXAMINE tells you whether the structure is OK. Use both when diagnosing and recovering a suspect KSDS.

Key Takeaways

• EXAMINE checks the structural integrity of a KSDS (index and data). It diagnoses; it does not fix data.
• Use INDEXTEST and DATATEST together for a full check. ERRORLIMIT(n) caps how many errors are reported.
• Condition code 0 = OK; 4 = OK with inconsistencies; 8 = corrupted, run VERIFY RECOVER and possibly restore from backup.
• EXAMINE is for KSDS. For catalog/end-of-data correction use VERIFY (and RECOVER).

Explain Like I'm Five

Imagine a filing cabinet (the KSDS): the index is like the labels on the drawers, and the data is the papers inside. EXAMINE is like a checker who looks at the labels to see if they point to the right drawers (INDEXTEST) and then opens each drawer to see if the papers are in the right order and nothing is torn or missing (DATATEST). The checker does not fix anything—they just write a report. If the report says "everything OK" (code 0), you can use the cabinet. If it says "broken" (code 8), you need to call someone to fix the catalog (VERIFY) or bring a backup cabinet (restore).

Test Your Knowledge