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


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.
General Rules
- 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 a STOP RUN statement causes a return value to be set in the
system area generally available for non-COBOL runtime 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. 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.
- When executed within a thread created with a START statement or the CBL_CREATE_THREAD
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.