Function
The CANCEL statement causes the specified program to be set to its initial state the next time it is called.
Format
CANCEL { identifier-1 | literal-1 } ...
Syntax rules
literal-1 must be an alphanumeric literal and must be a valid program name. However, it may not be a figurative constant.
If literal-1 is the program-name of a separately compiled program or of the outermost containing program of a nested program, it must begin with an alphabetic character and may contain only uppercase letters and digits. The length of the name depends on the module format.
If literal-1 is the program-name of a contained program of a nested program, it must begin with an alphabetic character, may contain uppercase letters, lowercase letters and digits, and must not be longer than 30 characters.identifier-1 must be defined as an alphanumeric data item so that its value may be a valid program name, as described under point 1.
General rules
literal-1 or the content of identifier-1 specifies the program which is to be set to its initial state.
Successful execution of the CANCEL statement closes the files in the specified program. If the program is called again in the same run unit or in a nested program after successful execution of a CANCEL statement, this program is in its initial state.
The program name specified as literal-1 or contained in identifier-1 must be unique within the run unit or the nested program unless it is a program name that may be used multiply under certain conditions (see section "CALL statement", general rule 4).
The program name must not be the same as the first 7 characters of the program name in the PROGRAM-ID paragraph of the program that contains the CANCEL statement.
Called programs may contain CANCEL statements, but a called program may not execute any CANCEL statement that either directly or indirectly references the calling program.
The logical connection to a program which is initialized with a CANCEL statement is established again only if this program is subsequently called again with a CALL statement.
A CANCEL statement has no effect if one of the following situations exists:
The program concerned is already in the initial state because it has not yet been called in the active run unit or in the nested program.
The program concerned has already been initialized with a CANCEL statement.
The program concerned or (with nested programs) a superordinate program has the INITIAL attribute..
In these cases, the program continues at the next executable statement after the CANCEL statement.
During execution of a CANCEL statement, an implicit CLOSE statement (without any optional phrases) is executed for each open internal file assigned to the program. Any USE procedures specified for these files are not executed.
A CANCEL statement may only reference such programs for which the call is permitted within the call hierarchy.
If an explicit or implicit CANCEL statement is executed, then all contained programs in the program referenced by the CANCEL statement are also cancelled.
Example 8-27
Main program:
IDENTIFICATION DIVISION.
PROGRAM-ID. MAIN.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 ERROR-CODE PIC 9.
88 O-K VALUE 0.
...
PROCEDURE DIVISION.
P1 SECTION.
MAIN.
PERFORM WITH TEST AFTER UNTIL O-K
CALL "UPROG1" USING ERROR-CODE
IF NOT O-K
THEN
CANCEL "UPROG1"
END-IF
END-PERFORM
STOP RUN.
Subprogram:
IDENTIFICATION DIVISION.
PROGRAM-ID. UPROG1.
ENVIRONMENT DIVISION.
DATA DIVISION.
...
LINKAGE SECTION.
01 ERROR-CODE PIC 9.
88 O-K VALUE 0.
PROCEDURE DIVISION USING ERROR-CODE.
...
IF INTERN-ERROR
THEN
CONTINUE
ELSE
SET O-K TO TRUE
END-IF
EXIT PROGRAM.
UPROG1 is called repeatedly until the value 0 is returned. As long as a value other than 0 is returned, UPROG1 is set to its initial state and the loop is continued.