COBOL VSAM KSDS batch update with INVALID KEY and DECLARATIVES error handling

Problem and takeaway

A batch update to a VSAM KSDS master must not abend on a missing key, duplicate key or transient I/O error. The reliable pattern is READ with explicit INVALID KEY handling for business conditions, and a DECLARATIVES USE AFTER-ERROR handler for system I/O errors, with a checkpoint log so the job can restart without partial updates.

Desired outcome

A repeatable job that opens an existing VSAM KSDS master, reads change records from a sequential input file, locates each master record by key, applies the change in WORKING-STORAGE, REWRITES the record with the key and length unchanged, and writes all errors to a report while continuing processing. Record counts are reconciled at the end.

Prerequisites

An existing VSAM KSDS cluster defined with RECORD KEY and a COBOL copybook that matches the on-disk layout exactly. A COBOL compiler that supports STANDARD-1/2 and DECLARATIVES, e.g. IBM Enterprise COBOL for z/OS, Micro Focus or GnuCOBOL. A sequential change file and a writable error report data set. Test data with known present, missing and duplicate keys.

Permissions required: read access to the VSAM cluster and change file, update access to the KSDS, write access to error and checkpoint logs. The job runs under a batch execution environment where the VSAM cluster is allocated via JCL DD.

File definition and program skeleton

SELECT the KSDS as INDEXED with RECORD KEY and ACCESS MODE IS DYNAMIC. The FD must match the copybook. WORKING-STORAGE holds the file status, a checkpoint counter and the error report record.

SELECT MASTER-FILE ASSIGN TO 'YOUR.VSAM.KSDS.CLUSTER'
    ORGANIZATION IS INDEXED
    ACCESS MODE IS DYNAMIC
    RECORD KEY IS MASTER-KEY
    FILE STATUS IS WS-MASTER-STAT.

FD MASTER-FILE.
01 MASTER-REC.
   05 MASTER-KEY PIC X(10).
   05 MASTER-DATA PIC X(100).
   COPY YOUR.COPYBOOK REPLACING ==...== BY ==...==.

DECLARATIVES provides a central I/O error trap. The handler logs the offending key and status and sets a flag to continue or abort.

DECLARATIVES.
USE AFTER ERROR PROCEDURE ON MASTER-FILE.
    MOVE WS-MASTER-STAT TO ERR-STAT
    MOVE MASTER-KEY TO ERR-KEY
    WRITE ERR-REC FROM ERR-DATA
    *> set a continuation flag, do not re-raise
END DECLARATIVES.

Processing loop with INVALID KEY

Open MASTER-FILE I-O and the change file INPUT-FILE for input. Verify OPEN status is 00 before processing.

OPEN I-O MASTER-FILE
     INPUT INPUT-FILE
     OUTPUT ERR-FILE.

For each change record: move the change key to MASTER-KEY, READ MASTER-FILE with INVALID KEY. If the key is not found, log a missing-key error and continue. If found, apply the change to the record buffer in WORKING-STORAGE without changing MASTER-KEY or record length, then REWRITE MASTER-REC with INVALID KEY to catch duplicate or integrity conditions.

READ MASTER-FILE INVALID KEY
    PERFORM LOG-MISSING-KEY
    CONTINUE
NOT INVALID KEY
    *> apply change to MASTER-DATA
    REWRITE MASTER-REC INVALID KEY
        PERFORM LOG-INVALID-REWRITE
        CONTINUE
    NOT INVALID KEY
        ADD 1 TO WS-UPDATED-COUNT
        MOVE CHANGE-KEY TO WS-LAST-KEY
        PERFORM WRITE-CHECKPOINT
    END-REWRITE
END-READ.

REWRITE requires the key and record length to be unchanged from the READ image. Changing the key or length can cause unpredictable results or data corruption.

Expected checks

After OPEN, file status must be 00. After each READ and REWRITE, inspect WS-MASTER-STAT. Non-zero status is logged to the error report with the key and a timestamp. At job end, close all files and compare input record count to updated count plus logged errors. The error log should contain entries for missing keys and INVALID KEY rewrites, and no abend should occur for trapped conditions.

Recovery and restart

Write a checkpoint record after each successful REWRITE containing the last processed change key and a sequence counter to a separate sequential checkpoint file. On restart, read the checkpoint, position the input file to the next record after the last successful key, and resume processing. The DECLARATIVES handler ensures I/O errors are logged rather than terminating the run, allowing the operator to decide whether to continue or stop.

Rollback is not automatic. Because REWRITE is atomic per record, partial updates are limited to the current record. If the job is stopped, the checkpoint allows reprocessing from the last known good point. Do not attempt to REWRITE with a changed key; that requires a DELETE followed by a WRITE with a new key.

Limitations and verification

VSAM KSDS behavior, status codes and DECLARATIVES syntax vary between IBM Enterprise COBOL for z/OS, Micro Focus and GnuCOBOL. Packed decimal COMP-3 fields require exact PIC and sign handling; mismatched copybooks cause numeric corruption on rewrite.

Verification steps for human review: compile with your compiler test option and run against a small test cluster. Inspect the error log for INVALID KEY and status entries to confirm error paths execute and processing continues. Re-run with a duplicate key and a missing key to verify the DECLARATIVES handler logs the condition and the checkpoint log allows restart. Compare output record counts and error log entries to expected values.