FILE STATUS and Handling Errors

If you have written any COBOL code that touches a file, you know that things can go wrong. What happens if you try to OPEN a file that does not exist? What if you do not have permission to read it?

In COBOL, you handle these scenarios by checking the FILE STATUS.

When you declare a FILE STATUS variable, the COBOL runtime will automatically update it after every input/output operation (OPEN, READ, WRITE, CLOSE). By checking this two-character alphanumeric variable, you can gracefully handle errors instead of having your program crash in the middle of the night.

Declaring a File Status Variable

To use FILE STATUS, you must explicitly declare it in two places:

1. In the FILE-CONTROL paragraph, using FILE STATUS IS.
2. In the WORKING-STORAGE SECTION, as a two-character alphanumeric item (PIC XX).

The standard strictly requires the variable to be alphanumeric, even though the status codes look like numbers.

       ID DIVISION.
       PROGRAM-ID. EX01.
       ENVIRONMENT DIVISION.
       INPUT-OUTPUT SECTION.
       FILE-CONTROL.
           SELECT F ASSIGN 'demo1.txt' ORGANIZATION LINE SEQUENTIAL
           FILE STATUS IS WS-FS.
       DATA DIVISION.
       FILE SECTION.
       FD F.
       01 R PIC X.
       WORKING-STORAGE SECTION.
       01 WS-FS PIC XX.
       PROCEDURE DIVISION.
           OPEN OUTPUT F.
           DISPLAY 'OPEN OUTPUT STATUS: ' WS-FS.
           CLOSE F.
           DISPLAY 'CLOSE STATUS: ' WS-FS.
           STOP RUN.

OPEN OUTPUT STATUS: 00
CLOSE STATUS: 00

If the operation is successful, the variable will contain '00'. Above, both our OPEN and CLOSE operations completed flawlessly, so they both logged '00'.

What Happens When Things Go Wrong?

One of the most common errors in data processing is attempting to open a file that simply isn’t there. If you don’t check for this, your program might abort unexpectedly.

Let’s see what happens if we attempt to open a file that does not exist. Read the code below and predict what the WS-FS variable will contain after the OPEN INPUT statement executes.

       ID DIVISION.
       PROGRAM-ID. EX02.
       ENVIRONMENT DIVISION.
       INPUT-OUTPUT SECTION.
       FILE-CONTROL. SELECT F ASSIGN 'no.txt'
           ORGANIZATION LINE SEQUENTIAL FILE STATUS WS-FS.
       DATA DIVISION.
       FILE SECTION.
       FD F. 01 R PIC X.
       WORKING-STORAGE SECTION.
       01 WS-FS PIC XX.
       PROCEDURE DIVISION.
           OPEN INPUT F.
           DISPLAY 'OPEN INPUT STATUS: ' WS-FS.
           STOP RUN.

OPEN INPUT STATUS: 35

A status code of '35' means the file was not found. If we check for this status right after our OPEN statement, we can display a helpful error message or create the file, rather than crashing.

Not All Non-Zero Codes Are Errors!

A common misconception is that any FILE STATUS other than '00' means a fatal error has occurred. This is false! Some status codes indicate expected lifecycle events.

For example, when you are reading a file sequentially, you will eventually reach the end. When this happens, the FILE STATUS becomes '10'.

       ID DIVISION.
       PROGRAM-ID. EX03.
       ENVIRONMENT DIVISION.
       INPUT-OUTPUT SECTION.
       FILE-CONTROL.
           SELECT F ASSIGN 'demo3.txt' ORGANIZATION LINE SEQUENTIAL
           FILE STATUS IS WS-FS.
       DATA DIVISION.
       FILE SECTION.
       FD F.
       01 R PIC X.
       WORKING-STORAGE SECTION.
       01 WS-FS PIC XX.
       PROCEDURE DIVISION.
           OPEN OUTPUT F. MOVE 'A' TO R. WRITE R. CLOSE F.
           OPEN INPUT F.
           READ F.
           DISPLAY 'READ 1 STATUS: ' WS-FS.
           READ F.
           DISPLAY 'READ 2 STATUS: ' WS-FS.
           CLOSE F.
           STOP RUN.

READ 1 STATUS: 00
READ 2 STATUS: 10

As you can see, the first read was successful ('00'), but the second read hit the end of the file, giving us the '10' status code. This is why a READ loop continues until it catches this specific code (often internally handled by the AT END phrase).

Using 88-Level Conditions for Cleaner Code

Because status codes are cryptic, seasoned COBOL developers use 88-level condition names in WORKING-STORAGE to make their PROCEDURE DIVISION highly readable. Instead of writing IF WS-FS = '35', you can define a descriptive name like FS-MISSING.

       ID DIVISION.
       PROGRAM-ID. EX05.
       ENVIRONMENT DIVISION.
       INPUT-OUTPUT SECTION.
       FILE-CONTROL.
           SELECT F ASSIGN 'demo5.txt' ORGANIZATION LINE SEQUENTIAL
           FILE STATUS IS WS-FS.
       DATA DIVISION.
       FILE SECTION.
       FD F.
       01 R PIC X.
       WORKING-STORAGE SECTION.
       01 WS-FS PIC XX.
          88 FS-OK VALUE '00'.
          88 FS-MISSING VALUE '35'.
       PROCEDURE DIVISION.
           OPEN INPUT F.
           IF FS-MISSING
               DISPLAY 'File is missing as expected.'
           END-IF.
           STOP RUN.

File is missing as expected.

Other Common Codes

File status codes are grouped by their first digit. Here are some you will encounter frequently:

• 0x: Successful completion (00 = success, 02 = duplicate key detected).
• 1x: End of data (10 = end of file).
• 2x: Invalid key condition (e.g. 22 = duplicate key written, 23 = record not found).
• 3x: Permanent errors (35 = file not found, 37 = permission denied).
• 4x: Logic errors (41 = already open, 42 = not open).

For instance, attempting to close a file that was never opened results in a '42'!

       ID DIVISION.
       PROGRAM-ID. EX06.
       ENVIRONMENT DIVISION.
       INPUT-OUTPUT SECTION.
       FILE-CONTROL.
           SELECT F ASSIGN 'demo6.txt' ORGANIZATION LINE SEQUENTIAL
           FILE STATUS IS WS-FS.
       DATA DIVISION.
       FILE SECTION.
       FD F.
       01 R PIC X.
       WORKING-STORAGE SECTION.
       01 WS-FS PIC XX.
       PROCEDURE DIVISION.
           CLOSE F.
           DISPLAY 'CLOSE STATUS WITHOUT OPEN: ' WS-FS.
           STOP RUN.

CLOSE STATUS WITHOUT OPEN: 42

Relying on FILE STATUS makes your COBOL programs incredibly resilient. Never assume a file operation worked—always check the status!