BY REFERENCE, CONTENT and VALUE
CALL passes addresses, not values, unless the program says otherwise. The three modes are a choice about what runs at that address: the caller storage itself, a copy made at the call, or the value in a register. The first two are the ones a COBOL program uses, and the difference between them is a class of bug that no compiler catches.
BY REFERENCE and BY CONTENT
One subprogram, called twice. The first call is the default mode, the second hands it a copy:
IDENTIFICATION DIVISION.
PROGRAM-ID. MAINP.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-A PIC 9(5) VALUE 100.
01 WS-B PIC X(8) VALUE "AAAA".
PROCEDURE DIVISION.
CALL "SET-IT" USING WS-A WS-B.
DISPLAY "reference " WS-A " " WS-B.
MOVE 100 TO WS-A.
MOVE "AAAA" TO WS-B.
CALL "SET-IT" USING BY CONTENT WS-A WS-B.
DISPLAY "content " WS-A " " WS-B.
STOP RUN.
END PROGRAM MAINP.
IDENTIFICATION DIVISION.
PROGRAM-ID. SET-IT.
DATA DIVISION.
LINKAGE SECTION.
01 L-NUM PIC 9(5).
01 L-TXT PIC X(8).
PROCEDURE DIVISION USING L-NUM L-TXT.
ADD 1 TO L-NUM.
MOVE "BBBB" TO L-TXT.
GOBACK.
END PROGRAM SET-IT.
cobc -x -free -Wall -o refcont refcont.cob
./refcont
reference 00101 BBBB
content 00100 AAAA
The first call changed the two fields of the caller, the second did not. BY CONTENT copies the arguments before the call and the subprogram works on the copies, so a callee that has to change something cannot be called that way. The mode is for a subprogram that only reads its arguments and whose caller wants to be sure it stays that way.
The copy is made once, at the call, and it is the size of the field of the caller, not the size of the linkage item. Both are 9(5) and X(8) here, which is the part of the contract the compiler does not check.
BY VALUE
BY VALUE passes the value itself, and the mode only makes sense for a binary numeric item: the receiving side sees a machine number, not a pointer. With a COMP-5 item it works, and the compiler warns that the feature is not finished in this version:
IDENTIFICATION DIVISION.
PROGRAM-ID. MAINP.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-A PIC S9(9) USAGE COMP-5 VALUE 100.
PROCEDURE DIVISION.
DISPLAY "start " WS-A.
CALL "BY-VALUE" USING BY VALUE WS-A.
DISPLAY "value " WS-A.
STOP RUN.
END PROGRAM MAINP.
IDENTIFICATION DIVISION.
PROGRAM-ID. BY-VALUE.
DATA DIVISION.
LINKAGE SECTION.
01 L-NUM PIC S9(9) USAGE COMP-5.
PROCEDURE DIVISION USING BY VALUE L-NUM.
ADD 1 TO L-NUM.
DISPLAY "inside " L-NUM.
GOBACK.
END PROGRAM BY-VALUE.
cobc -x -free -Wall -o val2 val2.cob
./val2
val2.cob:17: warning: handling of parameters passed BY VALUE is unfinished; implementation is likely to be changed [-Wunfinished]
15 | LINKAGE SECTION.
16 | 01 L-NUM PIC S9(9) USAGE COMP-5.
17 > PROCEDURE DIVISION USING BY VALUE L-NUM.
18 | ADD 1 TO L-NUM.
19 | DISPLAY "inside " L-NUM.
start +0000000100
inside +0000000101
value +0000000100
The subprogram saw 101 after its own addition and the caller still held 100: with a binary item the value is the copy, as with BY CONTENT, and the difference is only what travels in the call. The warning is part of the build on every platform of this version, and a program that needs to pass numbers to C should read it as a statement about this compiler rather than about its own code.
A BY VALUE call with a display item is accepted and the callee gets nonsense: the same call with the amount of PIC 9(5) DISPLAY instead of COMP-5 printed inside 40001 for a field that held 100. The first exercise at the end of the page asks for that run.
A linkage item that does not match
Nothing checks that a linkage item describes the same bytes as the argument. The subprogram gets the address and reads its own PIC there, which is why a mismatch corrupts data quietly:
IDENTIFICATION DIVISION.
PROGRAM-ID. MAINP.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-A PIC 9(5) VALUE 12345.
01 WS-B PIC X(4) VALUE "ABCD".
PROCEDURE DIVISION.
DISPLAY "caller " WS-A " " WS-B.
CALL "SHORT" USING WS-A WS-B.
DISPLAY "after " WS-A " " WS-B.
STOP RUN.
END PROGRAM MAINP.
IDENTIFICATION DIVISION.
PROGRAM-ID. SHORT.
DATA DIVISION.
LINKAGE SECTION.
01 L-A PIC 9(3).
01 L-B PIC X(2).
PROCEDURE DIVISION USING L-A L-B.
DISPLAY "callee " L-A " " L-B.
MOVE 999 TO L-A.
MOVE "ZZ" TO L-B.
GOBACK.
END PROGRAM SHORT.
cobc -x -free -Wall -o mismatch mismatch.cob
./mismatch
caller 12345 ABCD
callee 123 AB
after 99945 ZZCD
The callee read the first three characters of the five-digit field and wrote its 999 over them, and copied its two characters over the first two of the name. There was no error, no warning and no status: an address is an address. That is the reason a copybook shared by both sides, the subject of the copybook lesson, is worth the extra file.
Exercises
- Call SET-IT of the first program with a display item passed BY VALUE. Which number does the callee print?
- Change the second call of the first program to BY REFERENCE and run it again. Which two lines does the output hold?
- Give SHORT a PIC 9(5) linkage item for the first argument and run the program. What does the caller hold after the call?
- Pass WS-A of the first program to a subprogram whose linkage item is PIC X(5) and print it there. What does the callee see?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does BY REFERENCE pass to a subprogram?
Answer
The address of the caller storage, so a change is a change in the caller
The first call of the page left 00101 and BBBB in the caller.
-
What does BY CONTENT pass?
Answer
A copy, so the caller field keeps its value
The second call printed 00100 AAAA, the values the caller had set.
-
For which kind of item is BY VALUE meant?
Answer
A binary numeric item such as COMP-5
The COMP-5 call worked and the compiler warned that the feature is unfinished.
-
What does a linkage item with a different PIC than the argument do?
Answer
It describes the same bytes differently, so reads and writes land on the wrong characters
The callee read 123 of 12345 and wrote 999 over it: the caller held 99945 afterwards.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC 9(3) VALUE 500. 01 W-B PIC 9(3) VALUE 0. PROCEDURE DIVISION. CALL "Q5SUB" USING W-A W-B. DISPLAY W-B " " W-A. STOP RUN. END PROGRAM Q5. IDENTIFICATION DIVISION. PROGRAM-ID. Q5SUB. DATA DIVISION. LINKAGE SECTION. 01 L-A PIC 9(3). 01 L-B PIC 9(3). PROCEDURE DIVISION USING L-A L-B. MOVE L-A TO L-B. MOVE 1 TO L-A. GOBACK. END PROGRAM Q5SUB.Answer
500 001
The callee copied the amount into the second argument and then set the first to one, and both are the caller fields.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC X(4) VALUE "ABCD". PROCEDURE DIVISION. CALL "Q6SUB" USING W-A. DISPLAY W-A. STOP RUN. END PROGRAM Q6. IDENTIFICATION DIVISION. PROGRAM-ID. Q6SUB. DATA DIVISION. LINKAGE SECTION. 01 L-A PIC X(4). PROCEDURE DIVISION USING L-A. MOVE "WXYZ" TO L-A. GOBACK. END PROGRAM Q6SUB.Answer
WXYZ
The linkage item is the caller field, so the move is visible after the return.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC 9(5) VALUE 12345. PROCEDURE DIVISION. CALL "Q7SUB" USING BY CONTENT W-A. DISPLAY W-A. STOP RUN. END PROGRAM Q7. IDENTIFICATION DIVISION. PROGRAM-ID. Q7SUB. DATA DIVISION. LINKAGE SECTION. 01 L-A PIC 9(5). PROCEDURE DIVISION USING L-A. MOVE 1 TO L-A. GOBACK. END PROGRAM Q7SUB.Answer
12345
BY CONTENT gave the callee a copy, so the caller kept its value.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-N PIC 9 VALUE 0. PROCEDURE DIVISION. PERFORM 2 TIMES ADD 1 TO W-N END-PERFORM. DISPLAY W-N. STOP RUN. END PROGRAM Q8.Answer
2
Two passes add one each time, the shape a call in a loop has.
-
Why can a compiler not check the PIC of a linkage item against the argument?
Answer
The call is resolved at run time by name, and the argument is an address
The mismatch program built without a warning and wrote over the wrong bytes.
-
A subprogram only reads its arguments. Which mode says that best?
Answer
BY CONTENT, so the callee cannot change what the caller holds
The copy of BY CONTENT makes a writing callee harmless, at the cost of one copy per call.
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