IDCAMS DIAGNOSE

The IDCAMS DIAGNOSE command is used to analyze the structural consistency of VSAM catalogs and the relationship between the Basic Catalog Structure (BCS) and the volume-related information in the VVDS (Volume Table of Contents / Volume Verification Record). It identifies catalog-level problems such as name mismatches between the BCS and the VVR so you can correct them with recovery procedures. DIAGNOSE is a catalog-integrity tool: it focuses on the catalog itself, not on the contents of a single cluster. This page explains what DIAGNOSE does, how it differs from EXAMINE and VERIFY, common messages (e.g. IDC21364I reason code 12), and when and how to use DIAGNOSE as part of catalog recovery.

What DIAGNOSE Does

DIAGNOSE checks the integrity of catalog structures. In the Integrated Catalog Facility (ICF), the catalog has a BCS component that holds catalog entries (dataset names, types, attributes, volume references). Volume and allocation information is also stored in the VVDS (Virtual Volume Data Set) in the form of volume verification records (VVR). For consistency, the names and key fields in the BCS must match what is in the VVDS. DIAGNOSE compares these and reports when they do not match—for example when the catalog name, record name, subrecord name, or component name (DATA or INDEX) in the BCS differs from the VVR. It does not fix the catalog; it reports so that you or your procedures can run the appropriate recovery (e.g. DELETE NOSCRATCH, DEFINE RECATALOG, REPRO MERGECAT, or EXPORT/IMPORT with correct parameters). Exact syntax and options for DIAGNOSE can vary by z/OS and DFSMS release; consult the IBM z/OS DFSMS Access Method Services manual for your level.

When to Use DIAGNOSE

Use DIAGNOSE when: (1) You see catalog-related messages such as IDC21364I (catalog and VVDS names unequal) or other catalog integrity errors. (2) Datasets are not found or open fails with catalog-related return codes and you need to determine whether the catalog and VVDS are in sync. (3) You are performing catalog recovery or migration and need to verify BCS/VVR consistency before or after recovery steps. (4) Your site procedures require running DIAGNOSE as part of catalog health checks. Do not use DIAGNOSE to check a single cluster’s index or data (use EXAMINE) or to fix end-of-data after abnormal termination (use VERIFY). DIAGNOSE operates at the catalog level.

DIAGNOSE vs EXAMINE vs VERIFY

The three commands serve different purposes. VERIFY corrects the catalog entry and high-used RBA for a single cluster after abnormal termination. EXAMINE checks the structural integrity of one KSDS (index and data components) and reports damage. DIAGNOSE checks the catalog structure and BCS/VVR consistency and reports name mismatches and other catalog-level issues. So: VERIFY fixes catalog/end-of-data for a cluster; EXAMINE diagnoses one cluster’s structure; DIAGNOSE diagnoses the catalog and volume records.

BCS and VVR: What Must Match

For each catalog entry, the BCS and the VVDS (VVR) must agree on certain names. When DIAGNOSE finds a mismatch, it can report message IDC21364I with a reason code. Reason code 12 (RSN12) means the catalog name in the BCS and the name in the VVDS (VVR) are unequal. The four fields that must match exactly (including length) are: (1) Record name, (2) Subrecord name, (3) Component name (DATA or INDEX), and (4) Catalog name. If any of these differ between BCS and VVR, DIAGNOSE reports the error. The BCS error record offset in the message may point to a volume cell record; the actual problem is the name disagreement, not necessarily that specific record. Resolving RSN12 typically involves correcting the side that is wrong—either updating the BCS (e.g. delete and recatalog) or fixing the VVR (e.g. EXPORT/IMPORT with NEWNAMES where applicable), following IBM and your installation’s recovery procedures.

Recovery Options When DIAGNOSE Finds Errors

When DIAGNOSE reports catalog name mismatches or other catalog errors, recovery depends on which side (BCS or VVR) is correct and what your site allows. The following table summarizes typical approaches; always follow your installation’s procedures and IBM documentation.

IDCAMS DELETE with NOSCRATCH removes the catalog entry from the BCS but does not delete the dataset from the volume. You can then use DEFINE with RECATALOG to recatalog the dataset into the desired BCS so that names match. REPRO MERGECAT can move catalog records between catalogs. When the VVR is wrong, EXPORT/IMPORT with appropriate parameters (e.g. NEWNAMES) may be used to correct volume information; the exact steps are release-dependent. Catalog recovery is sensitive; coordinate with your system programming or storage team.

Running DIAGNOSE

DIAGNOSE is invoked like other IDCAMS commands: in a batch job with EXEC PGM=IDCAMS, SYSPRINT for output, and SYSIN containing the DIAGNOSE command. The exact syntax (catalog name, options) depends on your z/OS and DFSMS release. You may specify the catalog to diagnose and any scope or option parameters documented for your level. Output goes to SYSPRINT; review IDC messages and reason codes to determine what recovery is needed. Example (syntax may vary):

1
2
3
4
5
6
//DIAG     EXEC PGM=IDCAMS
//SYSPRINT DD   SYSOUT=*
//SYSIN    DD   *
  DIAGNOSE CATALOG(catalog-name)
/*
 

Replace catalog-name with the name of the catalog you want to diagnose. Refer to the IBM DFSMS Access Method Services manual for the full DIAGNOSE syntax and options on your release.

Key Takeaways

• DIAGNOSE checks catalog integrity and BCS/VVR consistency. It reports name mismatches and catalog-level errors; it does not fix them.
• IDC21364I with reason code 12 means the catalog name (or related names) in the BCS and VVR do not match. Recovery may use DELETE NOSCRATCH, DEFINE RECATALOG, REPRO MERGECAT, or EXPORT/IMPORT.
• Use DIAGNOSE for catalog-level diagnosis. Use EXAMINE for a single KSDS structure; use VERIFY to fix catalog and high-used RBA for a cluster.
• Always follow your site’s catalog recovery procedures and IBM documentation for your release.

Explain Like I'm Five

The catalog is like a big index that says "this file lives on this shelf (volume)". Sometimes the index and the labels on the shelf get out of sync—the index says one name and the shelf says another. DIAGNOSE is the person who checks the index and the shelf and says, "these don’t match here." They don’t fix it; they just report. Then someone else (you or your procedures) has to fix the index or the shelf so the names match again. EXAMINE is different: it checks one drawer (one cluster) to see if the papers inside are in order. VERIFY is the one that fixes the "where does the data end?" note in the catalog after something went wrong.

Test Your Knowledge