CALL and USING

A COBOL program is not one block of code. It is a main program and any number of subprograms, each with its own divisions, its own working storage and its own idea of what the parameters are. CALL connects them, and the connection is by name at run time, not by an import at compile time.

CALL and the LINKAGE SECTION

The subprogram declares the parameters in a LINKAGE SECTION and names the same list in its PROCEDURE DIVISION USING. The caller passes its own fields, and the subprogram sees them where its linkage items stand. This file holds both programs; cobc -x makes the first one the main program:

IDENTIFICATION DIVISION. PROGRAM-ID. MAINP. DATA DIVISION. WORKING-STORAGE SECTION. 01 WS-AMOUNT PIC 9(5) VALUE 1250. 01 WS-RESULT PIC 9(5) VALUE 0. PROCEDURE DIVISION. CALL "DOUBLE-IT" USING WS-AMOUNT WS-RESULT. DISPLAY "in " WS-AMOUNT " out " WS-RESULT. STOP RUN. END PROGRAM MAINP. IDENTIFICATION DIVISION. PROGRAM-ID. DOUBLE-IT. DATA DIVISION. WORKING-STORAGE SECTION. 01 WS-TEMP PIC 9(7). LINKAGE SECTION. 01 L-AMOUNT PIC 9(5). 01 L-RESULT PIC 9(5). PROCEDURE DIVISION USING L-AMOUNT L-RESULT. COMPUTE WS-TEMP = L-AMOUNT * 2 MOVE WS-TEMP TO L-RESULT GOBACK. END PROGRAM DOUBLE-IT.

cobc -x -free -Wall -o two two.cob
./two

in 01250 out 02500

Three details carry the whole mechanism. END PROGRAM closes each program, which is what lets two PROGRAM-ID entries live in one file. GOBACK returns to the caller, while STOP RUN would end everything. WS-TEMP is a seven-digit working-storage field because 2500 fits a five-digit one today and 99999 * 2 would not: the temporary belongs to the callee, not to the caller.

USING and BY REFERENCE

The parameter list is positional. The third argument of the caller is the third linkage item of the callee, whatever either is called, and the two sides have to agree on the PIC of every item. The default mode is BY REFERENCE: the callee works on the storage of the caller, so a change is a change in the caller too:

IDENTIFICATION DIVISION. PROGRAM-ID. MAINP. DATA DIVISION. WORKING-STORAGE SECTION. 01 WS-COUNT PIC 9(2) VALUE 0. 01 WS-TOTAL PIC 9(5) VALUE 0. 01 WS-AMOUNT PIC 9(5) VALUE 0. PROCEDURE DIVISION. MOVE 250 TO WS-AMOUNT. CALL "ADD-IT" USING WS-COUNT WS-TOTAL WS-AMOUNT. MOVE 40 TO WS-AMOUNT. CALL "ADD-IT" USING WS-COUNT WS-TOTAL WS-AMOUNT. MOVE 300 TO WS-AMOUNT. CALL "ADD-IT" USING WS-COUNT WS-TOTAL WS-AMOUNT. DISPLAY "count " WS-COUNT " total " WS-TOTAL. STOP RUN. END PROGRAM MAINP. IDENTIFICATION DIVISION. PROGRAM-ID. ADD-IT. DATA DIVISION. LINKAGE SECTION. 01 L-COUNT PIC 9(2). 01 L-TOTAL PIC 9(5). 01 L-AMOUNT PIC 9(5). PROCEDURE DIVISION USING L-COUNT L-TOTAL L-AMOUNT. ADD 1 TO L-COUNT. ADD L-AMOUNT TO L-TOTAL. GOBACK. END PROGRAM ADD-IT.

cobc -x -free -Wall -o refs refs.cob
./refs

count 03 total 00590

The counter and the total live in the caller and the subprogram changed them. The amount is passed as well and only read, so a program that restated it would be free to; the caller cannot tell from the call whether the callee writes to an argument.

STOP RUN in a subprogram

GOBACK and STOP RUN look interchangeable and are not. A subprogram that ends with STOP RUN ends the whole run, and the statement after the call never executes:

IDENTIFICATION DIVISION. PROGRAM-ID. MAINP. PROCEDURE DIVISION. DISPLAY "before the call". CALL "STOPPER". DISPLAY "after the call". STOP RUN. END PROGRAM MAINP. IDENTIFICATION DIVISION. PROGRAM-ID. STOPPER. PROCEDURE DIVISION. DISPLAY "inside". STOP RUN. END PROGRAM STOPPER.

cobc -x -free -Wall -o stoprun stoprun.cob
./stoprun

before the call
inside

The third line the caller wrote is missing and the exit status was 0: the run ended inside the subprogram as if the main program had ended. Every subprogram that is meant to return ends with GOBACK or with EXIT PROGRAM, and a STOP RUN inside one is a bug that shows up as a missing tail of a report.

A program that is not there

The name in CALL is resolved when the statement runs, from the programs linked into the executable or from a module file with that name. A name nobody supplies is a runtime error, not a compile error:

IDENTIFICATION DIVISION. PROGRAM-ID. MAINP. PROCEDURE DIVISION. DISPLAY "before". CALL "NOSUCHPROG". DISPLAY "after". STOP RUN. END PROGRAM MAINP.

cobc -x -free -Wall -o nocallee nocallee.cob
./nocallee

before
libcob: error: module 'NOSUCHPROG' not found

The build was clean, the message came at run time from the runtime library, and it ends with exit status 1. That is why a COBOL job ships its subprograms as modules beside the executable, or links them all into it: the compiler cannot see a name that is only decided when the call happens.

Exercises

  1. Add a fourth argument to ADD-IT in the caller only. What does the program do?
  2. Change the PIC of L-AMOUNT to 9(3) and run the program of the second section. Which total comes out, and why?
  3. Replace GOBACK in DOUBLE-IT with STOP RUN and run the first program. Which line disappears?
  4. Put the two programs of the first section in two files and build them with one cobc command. Which name has to come first?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. Where does a subprogram declare the parameters it receives?

    Answer

    In the LINKAGE SECTION, named again in PROCEDURE DIVISION USING

    The linkage items are the caller fields seen under other names.

  2. What does GOBACK do in a subprogram?

    Answer

    It returns to the caller

    The caller printed its line after the call, which STOP RUN would have prevented.

  3. What is the default parameter mode of CALL USING?

    Answer

    BY REFERENCE, so the callee works on the caller storage

    The counter and the total of the second program changed in the caller.

  4. What happens when a CALL names a program that does not exist?

    Answer

    The build succeeds and the run stops with module not found and exit status 1

    The message came from libcob at run time.

  5. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC 9(3) VALUE 250. 01 W-R PIC 9(3) VALUE 0. PROCEDURE DIVISION. CALL "Q5SUB" USING W-A W-R. DISPLAY W-R. STOP RUN. END PROGRAM Q5. IDENTIFICATION DIVISION. PROGRAM-ID. Q5SUB. DATA DIVISION. LINKAGE SECTION. 01 L-A PIC 9(3). 01 L-R PIC 9(3). PROCEDURE DIVISION USING L-A L-R. ADD 1 TO L-A. MOVE L-A TO L-R. GOBACK. END PROGRAM Q5SUB.

    Answer

    251

    The subprogram adds one to the caller field and copies it into the result.

  6. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-N PIC 9 VALUE 0. 01 W-T PIC 9(3) VALUE 0. PROCEDURE DIVISION. PERFORM 3 TIMES ADD 1 TO W-N ADD W-N TO W-T END-PERFORM. DISPLAY W-N " " W-T. STOP RUN. END PROGRAM Q6.

    Answer

    3 006

    Three passes add 1, 2 and 3, and the counter ends at 3.

  7. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC 9(5) VALUE 1250. 01 W-B PIC 9(7) VALUE 0. PROCEDURE DIVISION. COMPUTE W-B = W-A * 2 DISPLAY W-B. STOP RUN. END PROGRAM Q7.

    Answer

    0002500

    The seven-digit field holds 2500 with its leading zeros.

  8. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC X(5) VALUE "abc". PROCEDURE DIVISION. DISPLAY "[" FUNCTION TRIM(W-A) "]". STOP RUN. END PROGRAM Q8.

    Answer

    [abc]

    TRIM removes the two spaces the field holds after the letters.

  9. Two subprograms are linked into one executable. How are their names resolved?

    Answer

    At run time, from the programs of the executable or from modules of that name

    The missing name failed at run time and not in the build.

  10. Why does a subprogram keep its temporary result in its own working storage?

    Answer

    The linkage items belong to the caller, so a temporary needs storage the callee owns

    DOUBLE-IT computed into WS-TEMP and moved the result to the linkage item.

The code on this page was built with cobc (GnuCOBOL) 3.2.0 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev

Banner image