COBOL READ for VSAM

READ is the verb that pulls the next—or keyed—logical record from VSAM into your program buffer. For a KSDS opened with ACCESS MODE SEQUENTIAL, READ walks keys in order until VSAM signals end of file. For ACCESS MODE RANDOM, each READ expects you to have placed the target key into RECORD KEY before the call. For RRDS, the RELATIVE KEY data item names the slot you want. This page compares those patterns, explains FILE STATUS outcomes beginners should memorize first—especially 10 for sequential EOF and 23-style outcomes for missing keys—and contrasts INVALID KEY style coding with explicit status tests. It also warns about mixing READ formats in one paragraph without re-reading the manual, because Enterprise COBOL phrase compatibility is stricter than informal English descriptions suggest.

READ patterns at a glance

Sequential READ skeleton

1
2
3
4
5
6
7
8
       PERFORM UNTIL WS-FS = '10'
           READ CUSTFILE
           AT END
               MOVE '10' TO WS-FS
           NOT AT END
               PERFORM HANDLE-CUSTOMER-RECORD
           END-READ
       END-PERFORM

Some teams prefer omitting AT END and instead evaluate FILE STATUS after each READ without AT END; both styles work when used consistently. The sample shows AT END explicitly moving 10 for clarity in training; production code might centralize status handling in a copybook macro. Always ensure HANDLE-CUSTOMER-RECORD does not assume WS-FS remains 00 if inner paragraphs issue nested I/O that overwrites the status field—another classic bug source in large monoliths.

Random READ skeleton

1
2
3
4
5
6
7
8
9
10
11
       MOVE INCOMING-CUST-ID TO CUST-KEY
           READ CUSTFILE
           END-READ
           EVALUATE WS-FS
               WHEN '00'
                   PERFORM USE-CUST-RECORD
               WHEN '23'
                   PERFORM NOT-FOUND-PATH
               WHEN OTHER
                   PERFORM BAD-READ-STATUS
           END-EVALUATE

Use either INVALID KEY handling or post-READ FILE STATUS checks consistently per your shop standard. Some teams rely on INVALID KEY for indexed files; others read WS-FS only. For duplicate key clusters, understand whether READ retrieves the first duplicate or requires a browse sequence; that ties to DEFINE NONUNIQUEKEY and application design, not READ syntax alone.

INTO clause and length discipline

READ INTO requires the receiving item to be at least as large as the longest record you will accept. Variable-length VSAM files need LRECL tracking in working storage when you map payloads into substructures. Truncation silently loses data; guard with length checks when using DEPENDING ON clauses in the FD. Performance-sensitive shops sometimes avoid INTO for hot loops to reduce extra moves, but clarity often wins for maintenance-heavy batch.

Operational debugging tips

• Log first failing key value and FILE STATUS together; support teams reproduce faster.
• Compare COUNT of reads to control totals; missing increments often mean premature AT END handling.
• For intermittent 23, verify upstream data feeds did not introduce lowercase keys when keys are defined as uppercase EBCDIC zones.

KEY clause variants on READ

Advanced programs specify READ with KEY IS for alternate keys or partial key comparisons depending on compiler support and file definition. Beginners should master plain random READ using RECORD KEY in working storage before layering KEY IS phrases copied from decades-old examples. When KEY IS appears, double-check that the FD still matches LISTCAT alternate index definitions; alternate key offsets are easy to misalign because copybooks evolve faster than catalog ALTER tickets.

Numeric versus display keys

If the VSAM key is defined as display characters in COBOL but upstream feeds packed decimal numbers without reformatting, keys will never match even though math “looks the same” on green screen debuggers. Standardize MOVE to formatted DISPLAY fields before READ. For signed keys, agree whether the high-order nibble uses preferred sign encoding consistent with DEFINE. These sound like tiny details until a warehouse migration ships them wrong for a week.

Timeouts and long sequential passes

Jobs that READ sequentially through an entire multi-terabyte cluster need checkpointing and elapsed-time monitors. Without checkpoints, a late-night rerun repeats work from row zero. Without monitors, operations only learn the job hung when morning SLAs miss. Pair READ loops with counter DISPLAY throttled every hundred thousand rows or use SMF-exposed metrics so support can see progress. Combine with START-based restart if the job supports key-based resume rather than pure sequential rewinds from the beginning.

Hands-on exercises

1. Write a sequential read loop that stops on FILE STATUS 10 without using AT END; compare readability with a teammate.
2. Force random READ not-found and capture whether INVALID KEY, FILE STATUS, or both fire on your compiler level.
3. Instrument READ INTO with DISPLAY of length fields for a variable-length test file.

Explain Like I'm Five

READ is asking the librarian to hand you the next book from a shelf, or a specific book if you said the title first. Sequential READ is like reading the shelf left to right until empty. Random READ is like shouting one title and waiting for one book. Status 10 means “no more books that way.” Status 23-ish means “that title is not on the shelf.”

Test Your Knowledge