Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 38 ยท File Handling

File Status and Error Handling

Learn COBOL FILE STATUS codes, USE declaratives, AT END, INVALID KEY, ON SIZE ERROR and defensive patterns so batch programs fail loudly instead of corrupting data.

Batch programs run unattended at night. When a file is missing, a record is duplicated or a disk fills up, nobody is watching, so the program must notice and report precisely what went wrong. COBOL gives you several layers of error detection: the two-character FILE STATUS code, the AT END and INVALID KEY branches of I/O statements, ON SIZE ERROR for arithmetic, and USE declaratives as a safety net.

Without a status field, an I/O error on many compilers ends the run with a runtime message and no clean-up. With one, you decide what happens.

The FILE STATUS clause

Add a two-character field to Working-Storage and name it in the SELECT:

COBOL
           SELECT CUST-IN ASSIGN TO "customers.dat"
               ORGANIZATION IS LINE SEQUENTIAL
               FILE STATUS IS WS-CUST-STATUS.
       ...
       WORKING-STORAGE SECTION.
       01  WS-CUST-STATUS   PIC XX.
           88  CUST-OK          VALUE "00".
           88  CUST-EOF         VALUE "10".
           88  CUST-NOT-FOUND   VALUE "35".

After every OPEN, READ, WRITE, REWRITE, DELETE, START and CLOSE on that file, the runtime stores a code in WS-CUST-STATUS. The first digit gives the class:

Code Meaning
00 Successful
02 Successful, duplicate alternate key (indexed files)
04 Record length differs from the file's
10 End of file
14, 21 to 24 Key problems: out of sequence, invalid key, duplicate key 22, record not found 23, boundary 24
30 to 39 Permanent error: 35 file not found on OPEN INPUT, 37 open not permitted, 39 attribute conflict
41 to 49 Logic errors: 41 already open, 42 not open, 43 no prior read before REWRITE/DELETE, 46 read after end of file, 47 read on a file not opened for input, 48 write on a file not opened for output
9x Implementor-defined; IBM uses 90 series for VSAM problems, with a feedback code

The most useful ones to memorize are 00, 10, 22, 23, 35 and 46. Compilers may add their own details, so check your compiler's manual for the full list.

Checking after each statement

When a FILE STATUS field is present, a failed statement does not stop the program; your code must look at the status. A reusable pattern puts the check in a paragraph:

COBOL
       OPEN INPUT CUST-IN
       IF NOT CUST-OK
           DISPLAY "Cannot open customers: status " WS-CUST-STATUS
           MOVE 12 TO RETURN-CODE
           STOP RUN
       END-IF

Setting RETURN-CODE makes the job step end with a non-zero return code, which lets JCL, a scheduler or a shell script react (JCL for COBOL jobs). By convention 0 means success, 4 a warning, 8 an error, 12 a severe error and 16 a fatal one.

For reads, treat end-of-file as normal and everything else as an error:

COBOL
           READ CUST-IN
           EVALUATE TRUE
               WHEN CUST-OK     PERFORM PROCESS-RECORD
               WHEN CUST-EOF    SET AT-EOF TO TRUE
               WHEN OTHER       PERFORM FILE-ERROR
           END-EVALUATE

EVALUATE TRUE with condition names reads like a table of outcomes and makes it hard to forget a case.

AT END and INVALID KEY

These are the statement-level handlers:

  • READ ... AT END ... NOT AT END ... END-READ reacts to code 10.
  • READ, WRITE, REWRITE, DELETE, START on keyed files may use INVALID KEY ... NOT INVALID KEY for key problems such as 22 and 23 (indexed files).
COBOL
           WRITE CUST-REC
               INVALID KEY
                   DISPLAY "Duplicate customer " CUST-ID
               NOT INVALID KEY
                   ADD 1 TO WS-ADDED
           END-WRITE

If a statement can fail with an error that has neither a handler nor a FILE STATUS nor a USE declarative, the program ends abnormally. If you supply AT END or INVALID KEY, other errors still need a status field to be caught.

USE declaratives

A DECLARATIVES section at the start of the Procedure Division holds code the runtime calls when an I/O error occurs on a file that has no handler:

COBOL
       PROCEDURE DIVISION.
       DECLARATIVES.
       CUST-ERRORS SECTION.
           USE AFTER STANDARD ERROR PROCEDURE ON CUST-IN.
       CUST-ERROR-PARA.
           DISPLAY "I/O error on CUST-IN, status " WS-CUST-STATUS
           MOVE 16 TO RETURN-CODE
           STOP RUN.
       END DECLARATIVES.
       MAIN SECTION.
       MAIN-PARA.
           ...

Declaratives are a net below your explicit checks. They are handy when many statements could fail and checking each is noisy, but they cannot resume the statement; usually you report and stop. Once you start using sections the rest of the program must also be in sections.

Arithmetic errors: ON SIZE ERROR

A COMPUTE, ADD or other arithmetic statement that overflows its target field silently truncates the result unless you ask otherwise. ON SIZE ERROR runs when the result does not fit or you divide by zero:

COBOL
           COMPUTE AVG = TOTAL / COUNT
               ON SIZE ERROR
                   DISPLAY "Division problem, count=" COUNT
                   MOVE ZERO TO AVG
           END-COMPUTE

Without ON SIZE ERROR the target field's contents are undefined after a divide by zero on many systems. Pair it with a guard such as IF COUNT > 0 for clarity.

A reusable error paragraph

Collect the details in one place so every message is complete: the file name, the statement and the status.

COBOL
       FILE-ERROR.
           DISPLAY "FILE ERROR"
           DISPLAY "  file     : " WS-FILE-NAME
           DISPLAY "  operation: " WS-OPERATION
           DISPLAY "  status   : " WS-STATUS-ANY
           MOVE 16 TO RETURN-CODE
           PERFORM CLOSE-ALL-FILES
           STOP RUN.

Before each I/O statement you can MOVE "READ" TO WS-OPERATION. It costs one line and saves an hour in the middle of the night.

Seeing the logic

COBOL does not run here, so the block below is a Python stand-in labelled as a model of the READ/EVALUATE pattern. It simulates a file with a bad record and shows the decision on each status.

Python Stand-in: routing FILE STATUS codes like EVALUATE TRUE

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Stand-in: ON SIZE ERROR on a field that is too small

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The first line prints (Decimal('999.99'), False); the others print (None, True).

Common mistakes

  • Declaring FILE STATUS but never testing it: errors vanish and you process garbage.
  • Testing the status after a different statement than the one you meant. The field changes on every I/O.
  • Comparing status as a number: it is PIC XX, so compare with "00", not 0.
  • Continuing after 35 on OPEN: all later statements then fail with 42/47.
  • Treating 23 (not found) on a lookup as a crash when it is a normal business outcome.

Decide up front which codes mean "business as usual" (10, and 23 for optional lookups) and which stop the run. Put that decision in one paragraph.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does file status 10 mean?

    10 is the at-end condition. 00 is success, 35 is a missing file on OPEN and 22 a duplicate key.
  2. 2. What PICTURE is normally used for a FILE STATUS item?

    The status is two characters, so you compare it with literals such as "00".
  3. 3. What happens to a failed statement when a FILE STATUS field exists and you do not test it?

    The status handles the error from the runtime's point of view, so it is your job to inspect it.
  4. 4. Which clause catches arithmetic overflow and divide by zero?

    ON SIZE ERROR belongs to arithmetic statements such as COMPUTE, ADD and DIVIDE.

Summary

  • Declare FILE STATUS IS field for every file and test it after every I/O statement.
  • 00 is success, 10 end of file; keyed files add 22 duplicate, 23 not found; 35 means the file is missing.
  • AT END and INVALID KEY handle the expected outcomes; USE declaratives are a safety net.
  • ON SIZE ERROR protects arithmetic; set RETURN-CODE so the job step reports failure.

Next: Indexed and relative files