Library View Topics Framed Contents Revised Topics Previous Topic Next Topic Search Search ResultsPrevious Topic MatchNext Topic Match Notes List Notes Print Download No PDF Handheld DisconnectedHandheld ConnectedHelp

6.2.5 CANCEL Statement

The CANCEL statement ensures that the next time the referenced subprogram is called it will be entered in its initial state.

    ___ Format _____________________________________________________________ 
   |                                                                        |
   |             <__________________                                        |
   | >>__CANCEL____ _identifier-1_ _|____________________________________>< |
   |               |_literal-1____|                                         |
   |                                                                        |
identifier-1, literal-1
Literal-1 must be a nonnumeric literal. Identifier-1 must be an alphanumeric data item such that its value can be a program name. The rules of formation for program names are dependent on the PGMNAME compiler option. For details, see the discussion of program names in "PROGRAM-ID Paragraph" in topic 3.1.1 and also the description of the PGMNAME compiler option in the IBM COBOL Programming Guide for your platform.

X Identifier-1 can be alphabetic or zoned decimal data item. It cannot
X be a windowed date field.

Each literal or contents of the identifier specified in the CANCEL statement must be the same as the literal or contents of the identifier specified in an associated CALL statement.

X The program-name referenced in the CANCEL statement can be affected by
X the PGMNAME compiler option. For details, see the IBM COBOL
X Programming Guide for your platform.

X Do not specify the name of a class or a method in the CANCEL statement.

After a CANCEL statement for a called subprogram has been executed, that subprogram no longer has a logical connection to the program. The contents of data items in external data records described by the subprogram are not changed when that subprogram is canceled. If a CALL statement is executed later by any program in the run unit naming the same subprogram, that subprogram will be entered in its initial state.

When a CANCEL statement is executed, all programs contained within the program referenced by the CANCEL statement are also canceled. The result is the same as if a valid CANCEL were executed for each contained program in the reverse order in which the programs appear in the separately compiled program.

A CANCEL statement closes all open files that are associated with an internal file connector in the program named in the explicit CANCEL statement. Any USE procedures associated with any of these files are not executed.

You can cancel a called subprogram by referencing it as the operand of a CANCEL statement, by terminating the run unit of which the subprogram is a
X member, or by executing an EXIT PROGRAM statement or GOBACK statement in the called subprogram if that subprogram possesses the INITIAL attribute.

No action is taken when a CANCEL statement is executed, naming a program that either:

    • Under OS/390 and VM, has not been dynamically called in this run unit by another COBOL for MVS(R) & VM, COBOL for OS/390 & VM, VS COBOL II, or OS/VS COBOL program.
    • Under AIX, OS/2, and Windows, has not been called in this run unit by another IBM COBOL program.

  2. Has been called and subsequently canceled.

Called subprograms can contain CANCEL statements. However, a called program must not execute a CANCEL statement that directly or indirectly cancels the calling program itself, or any other program higher than itself in the calling hierarchy. In such a case, the run unit is terminated.

A program named in a CANCEL statement must not refer to any program that
X has been called and has not yet executed an EXIT PROGRAM or a GOBACK statement.

A program can, however, cancel a program that it did not call, providing that, in the calling hierarchy, it is higher than or equal to the program it is canceling. For example:

     A calls B and B calls C        (When A receives control,
                                     it can cancel C.)

A calls B and A calls C (When C receives control, it can cancel B.)

Previous Topic Next Topic Copyright IBM Corp. 1991, 1998

IBM Library Server Copyright 1989, 2005 IBM Corporation. All rights reserved.

Return to library:   z/OS | z/OS.e | TPF | z/VSE | z/VM | IBM Hardware | IBM System z Redbooks
Glossary:   IBM terminology
Publications:   How to order publications
Readers:   Download IBM Library Reader | Download IBM Softcopy Reader | Download Adobe® Acrobat® Reader®
Library management:   Download IBM Softcopy Librarian
Contacts:   Contact z/OS

Adobe, the Adobe logo, Acrobat, the Acrobat logo, and Acrobat Reader are registered trademarks of Adobe Systems incorporated.