MainframeMaster

COBOL Tutorial

COBOL STOP Statement - Quick Reference

The STOP statement in COBOL is used to terminate program execution and return control to the operating system or calling environment. It provides a clean way to end program execution and can optionally return a status code to the calling environment.

Primary Use

Terminate program execution

Division

PROCEDURE DIVISION

Type

Termination statement

Status

Required for program termination

Overview

The STOP statement is a fundamental COBOL statement used to terminate program execution. It immediately ends the program and returns control to the calling environment (operating system or calling program). The STOP statement can be used with or without a return code, allowing programs to communicate their completion status to the calling environment. This is essential for proper program flow control and error handling in COBOL applications.

Syntax

cobol
1
2
3
4
5
6
7
STOP RUN [RETURNING return-code].
 
* Examples:
STOP RUN.
STOP RUN RETURNING 0.
STOP RUN RETURNING WS-RETURN-CODE.
STOP RUN RETURNING 4.

Practical Examples

Basic STOP RUN Usage

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
* Basic STOP RUN example
IDENTIFICATION DIVISION.
PROGRAM-ID. BASIC-STOP-EXAMPLE.
 
DATA DIVISION.
WORKING-STORAGE SECTION.
01  WS-COUNTER           PIC 9(3) VALUE 0.
01  WS-MESSAGE           PIC X(50).
 
PROCEDURE DIVISION.
MAIN-LOGIC.
    DISPLAY "Program started"
    
    * Perform some processing
    PERFORM PROCESS-DATA
    
    * Display completion message
    MOVE "Processing completed successfully" TO WS-MESSAGE
    DISPLAY WS-MESSAGE
    
    * Terminate program
    STOP RUN.
 
PROCESS-DATA.
    PERFORM VARYING WS-COUNTER FROM 1 BY 1 UNTIL WS-COUNTER > 5
        DISPLAY "Processing iteration: " WS-COUNTER
    END-PERFORM.

Explanation: This example demonstrates basic usage of the STOP RUN statement. The program performs some processing (counting from 1 to 5) and then terminates cleanly with STOP RUN. This ensures that the program ends properly and returns control to the operating system. The STOP RUN statement is placed at the logical end of the program after all processing is complete.

STOP RUN with Return 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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
* STOP RUN with return codes example
IDENTIFICATION DIVISION.
PROGRAM-ID. STOP-RETURN-EXAMPLE.
 
DATA DIVISION.
WORKING-STORAGE SECTION.
01  WS-RETURN-CODE       PIC 9(2) VALUE 0.
01  WS-ERROR-FLAG        PIC X VALUE 'N'.
    88  ERROR-OCCURRED   VALUE 'Y'.
01  WS-FILE-STATUS       PIC X(2).
01  WS-RECORD-COUNT      PIC 9(5) VALUE 0.
 
PROCEDURE DIVISION.
MAIN-LOGIC.
    DISPLAY "Starting file processing program"
    
    * Open input file
    OPEN INPUT INPUT-FILE
    IF WS-FILE-STATUS NOT = "00"
        SET ERROR-OCCURRED TO TRUE
        MOVE 1 TO WS-RETURN-CODE
        GO TO PROGRAM-END
    END-IF
    
    * Process records
    PERFORM UNTIL WS-FILE-STATUS = "10"
        READ INPUT-FILE
            AT END
                CONTINUE
            NOT AT END
                IF WS-FILE-STATUS = "00"
                    ADD 1 TO WS-RECORD-COUNT
                    PERFORM PROCESS-RECORD
                ELSE
                    SET ERROR-OCCURRED TO TRUE
                    MOVE 2 TO WS-RETURN-CODE
                    GO TO PROGRAM-END
                END-IF
        END-READ
    END-PERFORM
    
    * Close file
    CLOSE INPUT-FILE
    IF WS-FILE-STATUS NOT = "00"
        SET ERROR-OCCURRED TO TRUE
        MOVE 3 TO WS-RETURN-CODE
    END-IF
    
    * Display results
    IF ERROR-OCCURRED
        DISPLAY "Program completed with errors"
    ELSE
        DISPLAY "Program completed successfully"
        DISPLAY "Records processed: " WS-RECORD-COUNT
    END-IF
 
PROGRAM-END.
    * Terminate with appropriate return code
    STOP RUN RETURNING WS-RETURN-CODE.
 
PROCESS-RECORD.
    * Process individual record logic here
    DISPLAY "Processing record number: " WS-RECORD-COUNT.

Explanation: This example shows how to use STOP RUN with return codes for proper error handling. The program sets different return codes based on the type of error encountered: 1 for file open errors, 2 for file read errors, and 3 for file close errors. A return code of 0 indicates successful completion. The program uses a common exit point (PROGRAM-END) to ensure consistent termination regardless of where errors occur. This approach allows the calling environment to determine the program's completion status.

Conditional STOP RUN

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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
* Conditional STOP RUN example
IDENTIFICATION DIVISION.
PROGRAM-ID. CONDITIONAL-STOP-EXAMPLE.
 
DATA DIVISION.
WORKING-STORAGE SECTION.
01  WS-USER-INPUT        PIC X(1).
01  WS-PROCESSING-FLAG   PIC X VALUE 'Y'.
    88  CONTINUE-PROCESSING VALUE 'Y'.
    88  STOP-PROCESSING     VALUE 'N'.
01  WS-RECORD-COUNT      PIC 9(3) VALUE 0.
 
PROCEDURE DIVISION.
MAIN-LOGIC.
    DISPLAY "Interactive processing program"
    DISPLAY "Press 'Q' to quit, any other key to continue"
    
    PERFORM UNTIL STOP-PROCESSING
        * Get user input
        ACCEPT WS-USER-INPUT
        
        * Check for quit command
        IF WS-USER-INPUT = 'Q' OR WS-USER-INPUT = 'q'
            SET STOP-PROCESSING TO TRUE
            DISPLAY "User requested program termination"
            STOP RUN RETURNING 0
        END-IF
        
        * Process data
        ADD 1 TO WS-RECORD-COUNT
        PERFORM PROCESS-USER-REQUEST
        
        * Check for maximum records
        IF WS-RECORD-COUNT >= 100
            DISPLAY "Maximum records processed, terminating"
            STOP RUN RETURNING 0
        END-IF
        
        DISPLAY "Records processed: " WS-RECORD-COUNT
        DISPLAY "Press 'Q' to quit, any other key to continue"
    END-PERFORM.
 
PROCESS-USER-REQUEST.
    DISPLAY "Processing request number: " WS-RECORD-COUNT
    * Add processing logic here
    DISPLAY "Request processed successfully".

Explanation: This example demonstrates conditional use of STOP RUN in an interactive program. The program continues processing until the user enters 'Q' to quit or until a maximum number of records (100) is processed. The STOP RUN statement is used in multiple locations to provide different exit points based on program conditions. This approach allows for flexible program termination based on user input or processing limits.

Error Handling with STOP RUN

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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
* Error handling with STOP RUN example
IDENTIFICATION DIVISION.
PROGRAM-ID. ERROR-HANDLING-STOP-EXAMPLE.
 
DATA DIVISION.
WORKING-STORAGE SECTION.
01  WS-RETURN-CODE       PIC 9(2) VALUE 0.
01  WS-ERROR-MESSAGE     PIC X(100).
01  WS-FILE-STATUS       PIC X(2).
01  WS-DIVIDEND          PIC 9(5).
01  WS-DIVISOR           PIC 9(3).
01  WS-RESULT            PIC 9(5)V99.
 
PROCEDURE DIVISION.
MAIN-LOGIC.
    DISPLAY "Error handling demonstration program"
    
    * Example 1: Division by zero error
    MOVE 1000 TO WS-DIVIDEND
    MOVE 0 TO WS-DIVISOR
    
    IF WS-DIVISOR = 0
        MOVE "Division by zero error" TO WS-ERROR-MESSAGE
        DISPLAY WS-ERROR-MESSAGE
        MOVE 10 TO WS-RETURN-CODE
        STOP RUN RETURNING WS-RETURN-CODE
    END-IF
    
    DIVIDE WS-DIVIDEND BY WS-DIVISOR GIVING WS-RESULT
    
    * Example 2: File access error
    OPEN INPUT NONEXISTENT-FILE
    IF WS-FILE-STATUS NOT = "00"
        MOVE "File access error" TO WS-ERROR-MESSAGE
        DISPLAY WS-ERROR-MESSAGE
        DISPLAY "File status: " WS-FILE-STATUS
        MOVE 20 TO WS-RETURN-CODE
        STOP RUN RETURNING WS-RETURN-CODE
    END-IF
    
    * Example 3: Data validation error
    IF WS-DIVIDEND < 0
        MOVE "Invalid dividend value" TO WS-ERROR-MESSAGE
        DISPLAY WS-ERROR-MESSAGE
        MOVE 30 TO WS-RETURN-CODE
        STOP RUN RETURNING WS-RETURN-CODE
    END-IF
    
    * Successful completion
    DISPLAY "All operations completed successfully"
    MOVE 0 TO WS-RETURN-CODE
    STOP RUN RETURNING WS-RETURN-CODE.

Explanation: This example shows how to use STOP RUN for comprehensive error handling. The program checks for various error conditions (division by zero, file access errors, data validation errors) and terminates with appropriate return codes when errors are detected. Each error condition has a unique return code (10, 20, 30) to help identify the specific error that occurred. The program only continues to the end if all operations are successful, returning a code of 0 for successful completion.

Best Practices and Considerations

Important Considerations

  • STOP RUN immediately terminates program execution
  • No statements after STOP RUN will be executed
  • Open files are automatically closed
  • Use return codes for proper error communication
  • Consider using common exit points for consistency

Advantages

  • Provides clean program termination
  • Automatically closes open files
  • Can return status codes to calling environment
  • Immediate program termination
  • Standard COBOL termination method

Limitations

  • Immediate termination - no cleanup code executed
  • Cannot be used in subprograms (use EXIT PROGRAM)
  • May not execute all cleanup logic
  • Return codes may not be supported in all environments
  • Can make debugging more difficult

Best Practices

  • • Always use STOP RUN to terminate main programs
  • • Use return codes to communicate program status
  • • Consider using common exit points for consistency
  • • Document return code meanings
  • • Ensure all necessary cleanup is done before STOP RUN

Test Your Knowledge

1. What is the primary purpose of the STOP statement in COBOL?

  • To pause program execution
  • To terminate program execution
  • To skip to the next statement
  • To restart the program

2. Which of the following is a valid STOP statement format?

  • STOP RUN
  • STOP PROGRAM
  • STOP EXECUTION
  • STOP END

3. What happens when a STOP RUN statement is executed?

  • The program pauses and waits for user input
  • The program terminates and returns control to the operating system
  • The program jumps to the next paragraph
  • The program restarts from the beginning

4. Can the STOP statement be used to return a specific return code?

  • No, it always returns zero
  • Yes, using STOP RUN RETURNING return-code
  • Only in some implementations
  • Only for batch programs

5. Where should the STOP RUN statement typically be placed in a COBOL program?

  • At the beginning of the program
  • In the middle of the main logic
  • At the end of the main processing logic
  • In every paragraph

Related Concepts

EXIT PROGRAM

Statement for terminating subprograms

PROCEDURE DIVISION

Division containing program logic and statements

Error Handling

Methods for handling program errors and exceptions

Program Structure

Overall organization of COBOL programs

Return Codes

Using return codes for program communication

STATUSSTRING and END-STRING