VSAM file status codes (COBOL)

FILE STATUS is how COBOL tells your program what happened after each I-O verb against a VSAM file. Two characters pack enormous diagnostic power: they distinguish happy path success from end-of-file, duplicate key writes, key not found, broken OPEN parameters, and dozens of other situations that would otherwise surface only as vague abends. Beginners should memorize a small spine of codes—00, 10, a few key-related twenties and thirties—and bookmark the IBM table for everything else. This page explains how to wire FILE STATUS in the SELECT clause, how to read the table responsibly (because exact meanings can vary slightly by compiler level and ACCESS mode), and how to pair status with LISTCAT or JCL when triage moves from application to infrastructure. Always verify critical codes against your installed Programming Guide before coding branches in production.

Wiring FILE STATUS

The SELECT assigns the name of the two-byte field. After OPEN, READ, WRITE, REWRITE, DELETE, and CLOSE, test the pair with 88-level condition names for readability. Avoid comparing only the first character unless you truly mean a family test; some distinctions use both digits.

1
2
3
4
5
6
       SELECT KSDS-FILE ASSIGN TO KSDSDD
              FILE STATUS IS WS-KSDS-STATUS.
       FD  KSDS-FILE ...
       01  WS-KSDS-STATUS PIC XX.
           88 KSDS-OK     VALUE "00".
           88 KSDS-EOF    VALUE "10".

Reference table (verify with your manual)

The meanings below are typical for Enterprise COBOL with VSAM; your release documentation is the source of truth. Use this table as a study aid, not a legal contract.

Mapping status to next diagnostic step

Thirties (35, 39, …)

Many thirties point to OPEN-time or definition mismatch: missing DD, wrong ORGANIZATION, conflicting ACCESS, or VSAM unable to open under current shareoptions. Start with JCL and LISTCAT before running EXAMINE.

Twenties related to keys

Invalid key, duplicate key, or sequence errors often mean program logic disagrees with data reality. Dump the key buffer in hex, confirm KEY clause lengths, and confirm the file really contains the key you expect after recent maintenance loads.

CICS note

CICS programs often use RESP and RESP2 instead of COBOL FILE STATUS for EXEC interface files, but batch COBOL still relies on FILE STATUS for VSAM datasets behind DD names. Know which runtime you are debugging before you search the wrong manual chapter.

Debugging workflow

When a status surprises you, write down the verb, the ACCESS mode, the OPEN mode, and the last successful key or RRN. Reproduce in a smaller extract using REPRO WITH FROMKEY/TOKEY so you can step through with DISPLAY statements without flooding production logs. Binary keys deserve hex dumps; display pictures lie. If the status maps to an environmental failure like 35, pivot to JCL and security before spending hours in application trace tables.

Testing strategy

Unit tests for VSAM paths should assert expected FILE STATUS values for happy path, duplicate insert, not found, and end-of-file. Many teams only assert numeric totals; adding status assertions catches regressions when copybooks change key offsets silently. Invest once in harness data fixtures that reload known keys between tests.

Practical exercises

1. Build 88-levels for the five statuses your shop handles most often.
2. Simulate a duplicate WRITE in sandbox and capture the exact status returned.
3. Highlight the VSAM FILE STATUS appendix in PDF and save to your team drive.

Explain like I'm five

FILE STATUS is the traffic light for your file operation. Green (00) means go. Yellow (like 10) might mean the road ends—no more houses on this street. Red (thirties) means stop and ask a grown-up to read the sign because something about the map (JCL) or the house number (key) is wrong.

Test your knowledge