The STOP Statement

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

ANS85The 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.

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

XOPENAlthough 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
Format 1
MFFormat 2
NETFormat 3
Syntax Rules
  1. Literal-1 must not be a figurative constant that begins with the word ALL.
  2. If literal-1 is numeric, then it must be an unsigned integer.

    OSVSVSC2A signed integer is allowed.

  3. MFInteger-1 may be signed.
  4. 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.

    OSVSVSC2MFThis rule is not enforced, although any statements in the sentence that follow the STOP RUN statement will not be executed.

  5. MFGIVING and RETURNING are equivalent.
  6. MFIdentifier-1 must be no larger than 8 bytes in size.
  7. MFIf 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.
  8. NETSTOP ITERATOR may only be specified in the context of an Iterator. See Iterator-ID.
General Rules
  1. If the RUN phrase is specified, execution of the run unit ceases and control is transferred to the operating system.
  2. 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.
  3. MFExecution 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.

    MFIf 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.)

    MFIf 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.

    MFIf 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.

  4. 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.
  5. 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
  6. MFSTOP 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.
  7. NETThe STOP ITERATOR statement has the effect of terminating the iterator.