The STOP Statement

The STOP statement causes a permanent or temporary suspension of the execution of the run unit.

The STOP literal statement is classed as an obsolete element in the ANSI'85 Standard and is scheduled to be deleted from the next full revision of the ANSI Standard.

All dialects within this COBOL implementation fully support this syntax. The FLAGSTD Compiler directive can be used to detect all occurrences of this syntax.

Although it is a part of the standard COBOL definition, the Stop literal format is explicitly excluded from the X/Open COBOL language definitions and should not be used in an X/Open COBOL conforming source program.

General Format for Format 1

General Format for Format 2

Syntax for format 2 of the STOP statement

General Format for Format 3

STOP ITERATOR

Syntax Rules

Literal-1 must not be a figurative constant that begins with the word ALL.
If literal-1 is numeric, then it must be an unsigned integer.
A signed integer is allowed.
Integer-1 may be signed.
If a STOP RUN statement appears in a consecutive sequence of imperative statements within a sentence, it must appear as the last statement in that sequence.
This rule is not enforced, although any statements in the sentence that follow the STOP RUN statement will not be executed.
GIVING and RETURNING are equivalent.
Identifier-1 must be no larger than 8 bytes in size.
If a STOP RUN GIVING statement is executed within a thread created with the START statement (format 3 threads) and if the ADDRESS OF clause is not specified, identifier-1 must be defined as either USAGE POINTER or a data item that is four bytes in size. The definition depends on the definition of the RETURNING item within the START statement. If identifier-1 is defined as a USAGE POINTER item, it must not be a function-identifier.
STOP ITERATOR may only be specified in the context of an Iterator. See Iterator-ID.

General Rules for All Formats

If the RUN phrase is specified, execution of the run unit ceases and control is transferred to the operating system.
During the execution of a STOP RUN statement, an implicit CLOSE statement without any optional phrases is executed for each file that is in the open mode in the run unit. Any USE procedures associated with any of these files are not executed.
Execution of the STOP RUN statement also frees all allocated buffers for dynamic-length elementary items for all programs in the run unit.
Execution of a STOP RUN statement causes a return value to be set in the system area generally available for non-COBOL run-time system elements to return a value. If the operating system supports the facility of returning a value from a program that is run to the operating system environment then it returns the value from the system area.
If the GIVING phrase is not specified then the run unit operates as if the system area were declared as a COBOL numeric data item with USAGE COMP-5 and with a size determined by the operating environment external to the COBOL system and as if a MOVE statement had been executed with the RETURN-CODE as the sending item and the system area as the receiving item. (See the topic Special Registers in the chapter Concepts of the COBOL Language for details of RETURN-CODE.)

If the GIVING identifier-1 phrase is specified, identifier-1 must describe the same number of character positions as is required to hold the return value in the system area and must be of the type and usage that is expected by the operating system. Typically, identifier-1 needs to be declared explicitly or implicitly as PIC S9 (9) USAGE COMP-5; this declaration depends on the value of the RTNCODE-SIZE Compiler directive. The run unit operates as if a MOVE statement had been executed with identifier-1 as the sending item and the system area as the receiving item.

If the GIVING integer-1 phrase is specified, integer-1 must not be larger than the value that can be held in the system area. The run unit operates as if a MOVE statement had been executed with integer-1 as the sending item and the system area as the receiving item.
If STOP literal-1 is specified, the execution of the run unit is suspended and literal-1 is communicated to the operator. Continuation of the execution of the run unit begins with the next executable statement when the operator presses the ENTER key or its equivalent.
Note: This behavior is not supported when initiated from a JCL batch job; processing will continue without operator intervention. Instead, use ACCEPT FROM CONSOLE syntax to achieve a similar effect when running via JCL.
When executed within a thread created with a START statement or the CBL_THREAD_CREATE library routine, a STOP RUN GIVING statement does not end the run-unit; it simply provides a return value and terminates the thread. It is equivalent to:
```
CALL 'CBL_THREAD_EXIT' USING BY VALUE ADDRESS OF thread-parm
```
STOP RUN in threads not created by the START statement or CBL_THREAD_CREATE library routine (that is, the main thread, or a thread created by a program written in another programming language) waits for all active CBL_THREAD_CREATE threads to finish and then terminates the run unit.
The STOP ITERATOR statement has the effect of terminating the iterator.

General Rules for Format 2

The RETURNING clause cannot return an object reference.