Implementing Robust File Status Checking for Sequential I/O in COBOL

Preventing Runtime Crashes with File Status Validation

COBOL programs that assume a file is always present or formatted correctly will crash with a system-level exception the moment an I/O operation fails. The most reliable way to prevent these crashes is to implement a FILE-STATUS check. This allows the program to intercept operating system return codes and handle errors—such as a missing file or the end of a data stream—gracefully rather than letting the runtime environment terminate the process.

Prerequisites

• A COBOL compiler (e.g., GnuCOBOL or IBM Enterprise COBOL).
• A sequential data file available in the environment's file system or JCL (Job Control Language) definition.
• Administrative permissions to read/write to the target directory.

Defining the Status Variable

The FILE-STATUS variable must be defined in the WORKING-STORAGE SECTION. It must be an alphanumeric field of exactly two characters, as the operating system returns a two-digit code representing the result of the last I/O operation.

DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-FILE-STATUS PIC X(2).

Linking the Variable to the File Description

To capture the status of a specific file, you must link the FILE-STATUS clause in the FILE SECTION to the variable defined in Working-Storage. This ensures that every OPEN, READ, and WRITE operation updates that specific variable.

FILE SECTION.
FD  INPUT-FILE
    FILE-STATUS IS WS-FILE-STATUS
    RECORDING MODE IS F
    RECORD CONTAINS 80 CHARACTERS.

Implementing the Validation Logic

Checking the status immediately after the I/O command is critical. Using an EVALUATE statement (similar to a switch/case in other languages) provides the cleanest way to handle multiple possible outcomes.

Example: Secure File Open and Read Loop

PROCEDURE DIVISION.
    OPEN INPUT INPUT-FILE
    IF WS-FILE-STATUS NOT = '00'
        DISPLAY 'ERROR OPENING FILE: ' WS-FILE-STATUS
        STOP RUN
    END-IF.

    PERFORM UNTIL WS-FILE-STATUS = '10'
        READ INPUT-FILE
        EVALUATE WS-FILE-STATUS
            WHEN '00'
                PERFORM PROCESS-RECORD
            WHEN '10'
                DISPLAY 'End of File reached successfully.'
            WHEN OTHER
                DISPLAY 'Fatal I/O Error: ' WS-FILE-STATUS
                STOP RUN
        END-EVALUATE
    END-PERFORM.

    CLOSE INPUT-FILE.
    STOP RUN.

Diagnostic Decision Table

When debugging I/O failures, use the following common status codes to determine the root cause:

Status Code	Meaning	Required Action
00	Success	Continue processing.
10	End of File (EOF)	Exit the read loop and close the file.
23	Key Not Found	Check if the record exists (common in indexed files).
30	Fatal Hardware/OS Error	Check file permissions or physical disk availability.
35	File Not Found	Verify the file path or JCL DD statement.

Verification and Testing

To verify that your error handling is functioning, perform the following tests:

1. Missing File Test: Rename your input file to something else and run the program. The program should display the error code (e.g., '35') and stop gracefully rather than crashing.
2. EOF Test: Run the program with a valid file. Ensure the loop terminates exactly when the last record is read, triggered by status '10'.
3. Permission Test: Change the file attributes to read-only and attempt an OPEN OUTPUT operation to verify that the status code captures the access violation.

Limitations and Risks

While FILE-STATUS is standard, some vendor-specific implementations may provide extended status codes or different numeric values for rare hardware failures. Always consult your specific compiler documentation (e.g., IBM Enterprise COBOL vs. GnuCOBOL) for edge-case codes.

Rollback Procedure

If the implementation of FILE-STATUS causes logic conflicts in legacy code, revert the changes by:

1. Removing the FILE-STATUS IS WS-FILE-STATUS clause from the FD entry.
2. Deleting the WS-FILE-STATUS variable from the WORKING-STORAGE SECTION.
3. Removing the EVALUATE or IF blocks following the I/O statements.