Return Codes and Job Flow

When a COBOL program finishes executing, it rarely does so in isolation. In mainframe environments, your program is usually just one step in a much larger Job Control Language (JCL) job schedule. The operating system needs to know if your program completed successfully or if it encountered an error, so it can decide whether to run the subsequent steps or halt the entire job.

This communication bridge between your COBOL program and the operating system is built using the RETURN-CODE special register and the JCL COND parameter.

The RETURN-CODE Special Register

The RETURN-CODE is a predefined special register implicitly defined by the COBOL compiler. You do not need to declare it in your DATA DIVISION. In GnuCOBOL, it is implicitly defined as a PIC S9(9) USAGE BINARY field initialized to zero when the program starts.

By standard convention across the industry:

• 0: Success
• 4: Warning (minor issues, but execution can continue)
• 8: Error (significant issues, subsequent steps usually skipped)
• 12: Severe Error (fatal issues, job halts)
• 16: Terminal Error (catastrophic failure)

To pass a status back to the operating system, you simply MOVE a numeric value into this register before your program ends.

       IDENTIFICATION DIVISION.
       PROGRAM-ID. SET-RC.
       PROCEDURE DIVISION.
           DISPLAY 'Processing data...'
           *> An error occurred, so we set a warning code:
           MOVE 4 TO RETURN-CODE
           DISPLAY 'Program exiting with RC: ' RETURN-CODE
           
           *> Reset to 0 for the automated test runner:
           MOVE 0 TO RETURN-CODE
           STOP RUN.

Processing data...
Program exiting with RC: +000000004

Note: The automated execution environment on this page requires programs to exit with 0 to mark a successful test run, which is why we reset it to 0 right before STOP RUN. In a real production program, you would leave it at 4.

JCL and the COND Parameter

Once your program exits, the operating system (e.g., z/OS) looks at the return code. If you have subsequent job steps lined up in your JCL, you can use the COND (Condition) parameter to tell the OS whether to execute them or bypass them.

Here is a visual representation of how job flow works:

The Counter-Intuitive Nature of COND

The most critical thing to understand about the JCL COND parameter is that it defines the condition for BYPASSING the step, not running it.

When you write COND=(4,EQ) in JCL, it translates to: “If 4 is Equal to the return code of the previous step, SKIP this step.” If the statement evaluates to TRUE, the step is bypassed. If it is FALSE, the step runs.

Dynamic Return Codes

You can use standard COBOL logic to determine the return code based on runtime conditions.

       IDENTIFICATION DIVISION.
       PROGRAM-ID. CALC-RC.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 RECORD-COUNT PIC 9(3) VALUE 500.
       PROCEDURE DIVISION.
           IF RECORD-COUNT > 200
               DISPLAY 'Warning: Unusually high record count.'
               MOVE 4 TO RETURN-CODE
           ELSE
               MOVE 0 TO RETURN-CODE
           END-IF
           
           DISPLAY 'Final RC will be ' RETURN-CODE
           
           *> Reset for test runner
           MOVE 0 TO RETURN-CODE
           STOP RUN.

Warning: Unusually high record count.
Final RC will be +000000004

Check Your Understanding

       IDENTIFICATION DIVISION.
       PROGRAM-ID. RC-PREDICT.
       PROCEDURE DIVISION.
           DISPLAY 'Default RC is: ' RETURN-CODE
           STOP RUN.

Default RC is: +000000000