IDCAMS VERIFY

The IDCAMS VERIFY command corrects the catalog and end-of-data information for a VSAM cluster (or alternate index) after abnormal termination or when the catalog is flagged. When a job abends, the system fails, or the job is cancelled while a VSAM file is open, the file may not be closed properly. The catalog can be left in a state that marks the dataset as possibly corrupt, and the high-used RBA (the "end of data" pointer) in the catalog may not match the actual data on disk. VERIFY compares the catalog with the physical cluster and updates the catalog so the dataset can be opened again and so the correct end-of-data is known. This page explains when to use VERIFY, the syntax (FILE(ddname) vs DATASET(name)), the RECOVER option, and how to use JOBCAT or STEPCAT when the cluster is in a user catalog without an alias.

When to Use VERIFY

Use VERIFY when the VSAM dataset was not closed normally or when the catalog entry is flagged. After VERIFY, the catalog is updated so that the high-used RBA and other metadata match the physical dataset, and the "corrupt" or "inconsistent" flag can be cleared. That allows programs to open the file again without getting open errors (e.g. return code 168). The following table lists common situations where VERIFY is needed.

What VERIFY Does

VERIFY does not change the record data on the volume. It updates the catalog (and possibly in-memory or on-disk control information) so that: (1) the high-used RBA in the catalog matches the actual end of valid data in the cluster, and (2) the catalog entry is no longer marked as inconsistent or corrupt. When a VSAM file is closed normally, the access method updates the catalog with the correct high-used RBA. When the job fails or is cancelled before close, that update may not happen. The catalog can then point to the wrong end-of-data or be flagged. VERIFY reads the physical cluster, determines the correct end-of-data, and writes the corrected information to the catalog. So VERIFY is a catalog-repair step, not a data-repair step. If the data itself was corrupted by the failure, you may need to restore from backup and then run VERIFY on the restored dataset.

Syntax: FILE(ddname) vs DATASET(name)

You specify the cluster to verify in one of two ways: FILE(ddname) or DATASET(dataset-name). FILE(ddname) means the cluster is allocated via a DD statement in your JCL; you give the DD name. DATASET(dataset-name) means you give the full catalog name of the cluster. Use FILE when the cluster is in a user catalog and you allocate it via a DD that points to the cluster (often with STEPCAT or JOBCAT pointing to the user catalog). Use DATASET when the cluster is in the default catalog or when the name will resolve via JOBCAT/STEPCAT. There is no CATALOG parameter on VERIFY; to use a user catalog you must make it available with JOBCAT or STEPCAT.

Complete Command Form

1
2
3
4
  VERIFY -
    { FILE(ddname) | DATASET(dataset-name) } -
    [ RECOVER ]
 

You must specify either FILE(ddname) or DATASET(dataset-name). RECOVER is optional. Continuation is with a hyphen at end of line. Example with FILE:

1
2
3
4
5
6
  //STEPCAT  DD DSN=USER.CATALOG,DISP=SHR
  //MYCLUST  DD DSN=MY.APPL.KSDS,DISP=OLD
  //SYSIN    DD *
    VERIFY FILE(MYCLUST)
  /*
 

Example with DATASET (cluster in default catalog):

1
2
  VERIFY DATASET(MY.APPL.KSDS)
 

Example with RECOVER after abnormal termination:

1
2
  VERIFY DATASET(MY.APPL.KSDS) RECOVER
 

JOBCAT and STEPCAT When No Catalog Alias

If the VSAM cluster is in a user catalog and there is no alias that makes that catalog the default, the step must have access to the user catalog. Allocate the user catalog with a JOBCAT or STEPCAT DD. JOBCAT applies to the whole job; STEPCAT applies to one step. The DD typically has DSN=user-catalog-name and DISP=SHR. Once the catalog is available, you can use VERIFY DATASET(cluster-name) if the cluster name is cataloged in that user catalog, or VERIFY FILE(ddname) where the DD points to the cluster (and the cluster may be opened through the same or another catalog). If you omit JOBCAT/STEPCAT and the cluster is only in a user catalog, the step cannot resolve the name and VERIFY will fail. So when there is no catalog alias, always use JOBCAT or STEPCAT and then VERIFY with DATASET(name) or FILE(ddname) as appropriate.

1
2
3
4
5
6
7
  //STEP1    EXEC PGM=IDCAMS
  //STEPCAT  DD DSN=MY.USER.CATALOG,DISP=SHR
  //SYSPRINT DD SYSOUT=*
  //SYSIN    DD *
    VERIFY DATASET(MY.APPL.PROD.KSDS)
  /*
 

VERIFY and Alternate Indexes

VERIFY is run per cluster. Verifying the base cluster does not verify its alternate indexes. If the base cluster was open at abnormal termination, run VERIFY on the base cluster. If an alternate index was also open (or if you are unsure), run VERIFY on each AIX that may have been affected. Each VERIFY command corrects one catalog entry (one cluster or one AIX). There is no single command that verifies the whole "sphere" (base plus all AIXs); you run VERIFY once for the base and once for each AIX as needed.

RECOVER Option

The RECOVER option tells VERIFY to attempt recovery of interrupted VSAM processing. That can include completing or backing out incomplete updates and correcting the catalog and dataset state. Use RECOVER when the dataset was left in an inconsistent state by abnormal termination—for example when a program was in the middle of an update or insert. After VERIFY RECOVER, you can run the EXAMINE command to check for remaining errors or damage. RECOVER may take longer than VERIFY without RECOVER because it does more work to restore consistency. See your IDCAMS documentation for the exact behavior of RECOVER on your system.

Return Codes and Empty Clusters

A successful VERIFY typically returns condition code 0 (or 4 in some cases). A non-zero return code indicates a problem—for example the dataset could not be opened, the catalog could not be updated, or the dataset was in an invalid state. VERIFY cannot be used on an empty VSAM file with a zero high-used RBA in some implementations; the documentation may say that the cluster must contain data. If your cluster is empty and you get an error, check whether your IDCAMS level allows VERIFY on empty clusters or whether you need to add at least one record before verifying.

Step-by-Step: After an Abend

1. Identify the VSAM cluster(s) that were open when the job abended or was cancelled.
2. Ensure no other job has the cluster open. If possible, keep the cluster offline until VERIFY is run.
3. If the cluster is in a user catalog without an alias, add JOBCAT or STEPCAT to the VERIFY step so the catalog is available.
4. Run IDCAMS with VERIFY FILE(ddname) or VERIFY DATASET(name). Add RECOVER if the failure may have left incomplete updates.
5. Check the IDCAMS return code and SYSPRINT. If VERIFY succeeds, the catalog is updated and the cluster can be opened again.
6. Optionally run EXAMINE to check for remaining errors. Then retry the application or restore from backup if data was corrupted.

Key Takeaways

• Use VERIFY after abnormal termination or when the catalog is flagged so the catalog and high-used RBA are correct.
• Use FILE(ddname) when the cluster is allocated via a DD (e.g. with STEPCAT); use DATASET(name) when referring by catalog name.
• When the cluster is in a user catalog with no alias, use JOBCAT or STEPCAT so the step can find the cluster.
• VERIFY does not change record data; it updates the catalog. Use RECOVER for interrupted processing; then EXAMINE if needed.
• Verify the base cluster and each affected alternate index separately.

Explain Like I'm Five

When you close a drawer (VSAM file) properly, the label (catalog) gets updated to say where the last thing is. If someone knocks over the cabinet (abend) before you close the drawer, the label might be wrong. VERIFY is like checking the drawer and fixing the label so it says the right place again. You can point to the drawer by its name (DATASET) or by the little card that points to it (FILE). If the drawer is in a different filing room (user catalog), you have to show the program the way to that room (JOBCAT/STEPCAT) first. After VERIFY, the label is fixed and people can use the drawer again.

Test Your Knowledge