Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 38 ยท Subprograms

CALL and the Linkage Section

Learn how COBOL programs call subprograms - CALL, USING BY REFERENCE, BY CONTENT and BY VALUE, the LINKAGE SECTION, GOBACK versus STOP RUN, static and dynamic calls, return codes and CANCEL.

A real COBOL system is rarely one program. A payroll run might have a main driver that reads employees and calls a tax subprogram, a date-validation subprogram and a report formatter. Splitting code this way gives you reusable pieces that many programs can share and that you can test one by one. The mechanism is the CALL statement together with the LINKAGE SECTION, where the called program describes the data it receives.

A caller and a subprogram

First the subprogram. It receives an amount and a state code and returns a tax amount:

COBOL
       IDENTIFICATION DIVISION.
       PROGRAM-ID. TAXCALC.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  WS-RATE          PIC V999.
       LINKAGE SECTION.
       01  LK-AMOUNT        PIC 9(7)V99.
       01  LK-STATE         PIC XX.
       01  LK-TAX           PIC 9(7)V99.
       PROCEDURE DIVISION USING LK-AMOUNT LK-STATE LK-TAX.
       MAIN.
           EVALUATE LK-STATE
               WHEN "CA" MOVE .0725 TO WS-RATE
               WHEN "NY" MOVE .0400 TO WS-RATE
               WHEN OTHER MOVE .0600 TO WS-RATE
           END-EVALUATE
           COMPUTE LK-TAX ROUNDED = LK-AMOUNT * WS-RATE
           GOBACK.

And the caller:

COBOL
       IDENTIFICATION DIVISION.
       PROGRAM-ID. ORDERS.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  WS-AMOUNT   PIC 9(7)V99 VALUE 200.00.
       01  WS-STATE    PIC XX      VALUE "CA".
       01  WS-TAX      PIC 9(7)V99.
       PROCEDURE DIVISION.
       MAIN.
           CALL "TAXCALC" USING WS-AMOUNT WS-STATE WS-TAX
           DISPLAY "Tax: " WS-TAX
           STOP RUN.

200.00 x 0.0725 = 14.50, so the caller shows Tax: 000001450 (nine digits, implied point). Walk through the pieces:

  • CALL "TAXCALC" transfers control to the program with that PROGRAM-ID.
  • USING lists the items passed. The order matters: the first item matches LK-AMOUNT, the second LK-STATE, and so on.
  • The subprogram's PROCEDURE DIVISION USING names its parameters. The items are not allocated in the subprogram; the LINKAGE SECTION only describes how to view the caller's storage.
  • GOBACK returns to the caller. STOP RUN in a subprogram would end the whole run, usually a mistake. In the main program GOBACK and STOP RUN behave alike.
  • The caller and callee match parameters by position, never by name, and the compiler does not check that the lengths agree. A mismatch compiles and then misbehaves at run time, so keep one shared description of the layout in a copybook (copybooks).
sequenceDiagram
    participant M as ORDERS (caller)
    participant T as TAXCALC (callee)
    M->>T: CALL USING amount, state, tax
    T->>T: compute with LINKAGE items
    T-->>M: GOBACK (tax filled in)

Parameters travel as addresses of the caller's data, so the callee's changes show up in the caller.

How parameters are passed

USING can name one of three methods for each argument:

Phrase What the callee gets Typical use
BY REFERENCE (the default) The address of the caller's item; changes are visible Results, in-out values, big groups
BY CONTENT The address of a copy; the caller's item is not changed Inputs that must not be altered, literals
BY VALUE The value itself (usually for numeric items and C interoperability) Calling C functions, RETURNING APIs
COBOL
           CALL "TAXCALC" USING BY CONTENT WS-AMOUNT
                                BY CONTENT WS-STATE
                                BY REFERENCE WS-TAX

This makes it obvious which parameters are inputs and which one is the result. A literal can be passed only by content: CALL "TAXCALC" USING BY CONTENT 200.00 .... When an argument is passed by value, the callee declares it with PROCEDURE DIVISION USING BY VALUE LK-N (and the item in the Linkage Section must be an elementary numeric item such as PIC S9(9) COMP-5).

Returning a value

Beyond updating parameters there are two ways to hand a result back:

  1. RETURN-CODE: a special register every program has; the callee sets it and the caller reads it after the call. It is a binary number, good for status values.
  2. RETURNING: CALL "ADD-TWO" USING BY VALUE A B RETURNING R and PROCEDURE DIVISION USING BY VALUE A B RETURNING R. It maps neatly to functions and to C.

Prefer an explicit status item among the parameters over relying on RETURN-CODE, because other CALLs in between can overwrite it.

Static and dynamic calls

CALL "TAXCALC" with a literal is normally a static call on IBM compilers (the subprogram is link-edited into the same load module). CALL WS-PROG-NAME with a data item holds the name at run time and is a dynamic call: the system loads the program the first time it is called. Dynamic calls let you replace a subprogram without relinking the caller, and they let you choose which program to run from data, which suits plug-in logic.

COBOL
           MOVE "TAXCALC" TO WS-PROG-NAME
           CALL WS-PROG-NAME USING WS-AMOUNT WS-STATE WS-TAX
               ON EXCEPTION
                   DISPLAY "Program not found: " WS-PROG-NAME
               NOT ON EXCEPTION
                   CONTINUE
           END-CALL

ON EXCEPTION runs when the program cannot be loaded. GnuCOBOL treats both forms as dynamic unless you compile with -static options.

Program state: initial and CANCEL

The second time you CALL a subprogram, its Working-Storage still holds whatever the first call left, unless the program says PROGRAM-ID. TAXCALC IS INITIAL. (state reset at every call) or the caller issues CANCEL "TAXCALC" (for dynamic calls: the program is unloaded and next time starts fresh).

This is useful and dangerous at once. A counter that you forget to reset keeps counting; on the other hand a loaded rate table need not be read again. A well-written subprogram initializes what it needs on every call, or uses a first-time flag:

COBOL
       01  WS-FIRST-TIME PIC X VALUE "Y".
       ...
           IF WS-FIRST-TIME = "Y"
               PERFORM LOAD-RATE-TABLE
               MOVE "N" TO WS-FIRST-TIME
           END-IF

Passing tables, groups and files

You can pass a group item and describe it in more detail in the callee, as long as the layout matches. Passing a table is as simple as passing its 01 name. Files cannot be passed to a subprogram: open them in the one that owns them, and pass records to and from the other. A subprogram may use EXTERNAL data and GLOBAL items to share files, but explicit parameters are easier to follow.

Seeing the parameter methods

COBOL is not runnable on the site; these are Python stand-ins that model the call methods. A mutable list plays the part of "storage the callee can change".

Python Stand-in: BY REFERENCE versus BY CONTENT

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The first line shows the careless callee zeroing the caller's amount; in the second line the amount survives because the callee only touched the copy.

Python Stand-in: subprogram state between calls (IS INITIAL and CANCEL)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The three lines print [1, 2, 3], [1, 1, 1] and 1.

Common mistakes

  • Different parameter counts or sizes in caller and callee: no compile error, wrong data at run time.
  • Using STOP RUN in a subprogram, which ends the entire run unit.
  • Assuming Working-Storage is reset between calls.
  • Calling with a literal BY REFERENCE and letting the callee modify it.
  • Mixing COMP fields of different sizes across programs compiled with different options.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which statement ends a subprogram and returns to its caller?

    GOBACK returns to the caller (or ends the run when used in a main program). STOP RUN in a subprogram ends everything.
  2. 2. What does BY CONTENT pass?

    The callee can change its copy without affecting the caller's data.
  3. 3. Where does the called program describe the parameters it receives?

    LINKAGE items map onto the storage passed by the caller.
  4. 4. How do caller and callee match parameters?

    The first USING item corresponds to the first parameter, and so on; names do not matter.

Summary

  • CALL "PROG" USING ... runs another program; the callee names its parameters with PROCEDURE DIVISION USING and describes them in the LINKAGE SECTION.
  • Parameters match by position. Use BY REFERENCE for results, BY CONTENT for protected inputs and BY VALUE for C-style calls.
  • End a subprogram with GOBACK; use RETURNING or an explicit status parameter for results.
  • Literal calls are usually static, data-name calls dynamic; INITIAL and CANCEL control retained state.

Next: Copybooks and nested programs