MainframeMaster

COBOL Tutorial

COBOL PROGRAM-STATUS - Quick Reference

Progress0 of 0 lessons

Overview

PROGRAM-STATUS is a special register in COBOL that contains the execution status or return code of a program. It is automatically set by the system when a program completes execution and can be checked by calling programs to determine if the called program executed successfully.

Purpose and Usage

  • Program execution monitoring
  • Error handling and status checking
  • Return code management
  • Program flow control
  • System integration

Syntax

PROGRAM-STATUS is a special register that can be referenced directly:

Checking PROGRAM-STATUS

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
* Checking PROGRAM-STATUS after program call
CALL "subprogram-name" USING parameters.
IF PROGRAM-STATUS = 0
    DISPLAY "Program executed successfully"
    PERFORM success-processing
ELSE
    DISPLAY "Program failed with status: " PROGRAM-STATUS
    PERFORM error-handling
END-IF.
 
* Multiple status checks
CALL "data-processor" USING input-data.
EVALUATE PROGRAM-STATUS
    WHEN 0
        DISPLAY "Success"
        PERFORM normal-processing
    WHEN 8
        DISPLAY "Abnormal termination"
        PERFORM cleanup-processing
    WHEN 12
        DISPLAY "Program not found"
        PERFORM error-recovery
    WHEN OTHER
        DISPLAY "Unexpected status: " PROGRAM-STATUS
        PERFORM general-error-handling
END-EVALUATE.

PROGRAM-STATUS can be checked using conditional statements.

Setting Return Codes

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
* Setting return code in called program
PROCEDURE DIVISION.
MAIN-PROCESS.
    * Program logic here
    IF processing-successful
        STOP RUN 0
    ELSE
        STOP RUN 8
    END-IF.
 
* Alternative method
PROCEDURE DIVISION.
MAIN-PROCESS.
    * Program logic here
    IF critical-error
        MOVE 16 TO return-code
        STOP RUN return-code
    END-IF.
    
    * Normal completion
    STOP RUN 0.

Practical Examples

Here are some practical uses of PROGRAM-STATUS in COBOL:

Program Chain with Status Checking

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
* Main program calling subprograms
PROCEDURE DIVISION.
MAIN-PROCESS.
    * Call data validation program
    CALL "validate-data" USING input-records.
    IF PROGRAM-STATUS NOT = 0
        DISPLAY "Data validation failed"
        PERFORM error-exit
    END-IF.
    
    * Call data processing program
    CALL "process-data" USING input-records.
    IF PROGRAM-STATUS NOT = 0
        DISPLAY "Data processing failed"
        PERFORM error-exit
    END-IF.
    
    * Call report generation program
    CALL "generate-report" USING processed-data.
    IF PROGRAM-STATUS NOT = 0
        DISPLAY "Report generation failed"
        PERFORM error-exit
    END-IF.
    
    DISPLAY "All processing completed successfully"
    STOP RUN 0.
 
ERROR-EXIT.
    DISPLAY "Program terminated due to error"
    STOP RUN 8.

Checking PROGRAM-STATUS after each program call.

Error Handling with Status Codes

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
* Comprehensive error handling
PROCEDURE DIVISION.
CALL-UTILITY-PROGRAMS.
    * Call file utility
    CALL "file-utility" USING file-parameters.
    EVALUATE PROGRAM-STATUS
        WHEN 0
            DISPLAY "File operation successful"
        WHEN 4
            DISPLAY "File not found - using default"
            PERFORM use-default-file
        WHEN 8
            DISPLAY "File access error"
            PERFORM file-error-recovery
        WHEN 12
            DISPLAY "Utility program not found"
            PERFORM alternative-processing
        WHEN OTHER
            DISPLAY "Unexpected error: " PROGRAM-STATUS
            PERFORM general-error-handling
    END-EVALUATE.
    
    * Continue with next operation
    CALL "data-processor" USING data-parameters.
    IF PROGRAM-STATUS = 0
        PERFORM continue-processing
    ELSE
        PERFORM handle-processing-error
    END-IF.

Detailed error handling based on PROGRAM-STATUS values.

Best Practices

  • Always check PROGRAM-STATUS after calling other programs.
  • Use meaningful return codes that indicate specific error conditions.
  • Document the meaning of return codes in your programs.
  • Handle all possible return code values, not just success (0).
  • Provide appropriate error messages and recovery actions.
  • Consider using EVALUATE for complex status checking logic.

Common Pitfalls

  • Not checking PROGRAM-STATUS after program calls.
  • Assuming all programs return 0 for success.
  • Not handling unexpected return codes.
  • Using inconsistent return code values across programs.
  • Not providing meaningful error messages for different status codes.

Test Your Knowledge

1. What is PROGRAM-STATUS in COBOL?

  • A data type for storing program information
  • A special register that indicates program execution status
  • A file status indicator
  • A program counter

2. What does PROGRAM-STATUS contain?

  • Program name
  • Return code or execution status
  • File information
  • Memory address

3. When is PROGRAM-STATUS typically used?

  • During program compilation
  • After program execution to check results
  • During file operations
  • During data input

4. What is a common return code for successful execution?

  • 0
  • 1
  • 8
  • 16

5. How do you check PROGRAM-STATUS in a calling program?

  • Using IF PROGRAM-STATUS = 0
  • Using CHECK PROGRAM-STATUS
  • Using TEST PROGRAM-STATUS
  • Using VERIFY PROGRAM-STATUS

Frequently Asked Questions

Related Concepts

CALL Statement

Calling other programs in COBOL.

Error Handling

Comprehensive error handling strategies.

Program Flow Control

Managing program execution flow.

Return Codes

Understanding and using return codes.

System Integration

Integrating COBOL programs with systems.

POINTER-64RAISE