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.
- Literal-1 must not be a figurative constant that begins with the
- If literal-1 is numeric, then it must be an unsigned integer.
A signed integer is
- 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
- STOP ITERATOR may only be specified
in the context of an Iterator. See
- 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
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.
- The STOP ITERATOR statement has the
effect of terminating the iterator.