COBOL CALL and CANCEL

CALL runs another program (a subprogram); CANCEL removes a dynamically called subprogram from memory and resets its state so the next CALL loads it again. Together they support dynamic loading and memory management when the program name is in a variable. For full CALL syntax and parameter passing see CALL; this page focuses on the CALL-and-CANCEL pair for dynamic subprograms.

Key terms

Why use CANCEL?

With a dynamic CALL (program name in a data item), the subprogram is loaded when first called. It stays in memory for later calls. CANCEL unloads it: storage is freed, and the next CALL loads a fresh copy from disk. That fresh copy starts with initial values in working storage and no leftover state. Use CANCEL when you want to free memory, force a clean state on the next call, or ensure the subprogram is reloaded (e.g. after a copy was replaced).

Syntax

CALL (dynamic)

1
2
3
4
5
6
7
8
       WORKING-STORAGE SECTION.
       01  PGM-NAME    PIC X(8) VALUE 'UTILPGM'.
 
       PROCEDURE DIVISION.
           CALL PGM-NAME USING WS-IN, WS-OUT
               ON EXCEPTION
                   DISPLAY 'CALL failed'
           END-CALL.

CANCEL

1
2
3
       CANCEL PGM-NAME
       *> or CANCEL "UTILPGM"
       *> Subprogram is removed from memory; next CALL loads it again.

What CANCEL does

• Removes the subprogram from memory and releases its storage.
• Resets the program so the next CALL loads it again from disk in initial state.
• Closes any files that were open in the canceled program.
• If the program contains other programs (nested), those are canceled too.

CANCEL has no effect if the program was never called or is already canceled. Only the calling program (or one above it in the call stack) should CANCEL a given program; you cannot cancel a program that is above you in the hierarchy.

Example: Dynamic call and cancel

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
       WORKING-STORAGE SECTION.
       01  SUBPGM-NAME   PIC X(20).
       01  WS-INPUT      PIC X(50).
       01  WS-OUTPUT     PIC X(100).
 
       PROCEDURE DIVISION.
       MAIN.
           MOVE 'VALIDATE-DATA' TO SUBPGM-NAME
           CALL SUBPGM-NAME USING WS-INPUT WS-OUTPUT
               ON EXCEPTION
                   DISPLAY 'Validate program not found'
               NOT ON EXCEPTION
                   DISPLAY 'Validation done'
                   *> Free memory and reset; next CALL loads fresh
                   CANCEL SUBPGM-NAME
           END-CALL
           GOBACK.

When to use CANCEL

• After dynamic calls when you want to free memory (e.g. large or rarely used subprograms).
• When the subprogram must start in a clean state on the next call (no leftover working storage).
• When you have multiple different program names in a variable and you want to ensure the correct one is loaded next time.

Step-by-step: Dynamic call and cancel

• Move the subprogram name to a data item (e.g. PIC X(8)).
• CALL that data item USING your parameters; handle ON EXCEPTION if the program is missing or fails to load.
• When you are done with the subprogram for a while (or want a clean state), execute CANCEL with the same program name (literal or data item).
• The next CALL to that program will load it again from disk with initial state.

Explain like I'm five

CALL is like asking a friend to do a task; they come over (load) and do it. If you don’t say “you can go home” (CANCEL), they stay. CANCEL means “go home and forget what we did.” Next time you call, they come again and start from scratch. That way you don’t have too many friends sitting in the room (memory), and each visit starts fresh.

Related Concepts