RETURNING and RETURN-CODE
A subprogram that only writes to its parameters has no way to say that it worked. COBOL has three answers: the special register RETURN-CODE, an ordinary parameter the caller inspects, and the RETURNING phrase of CALL. This page shows all three, and the third one does not work in this compiler.
RETURN-CODE
RETURN-CODE is a special register every program of the run shares. A subprogram that moves a number to it and returns sets the status the caller reads; and because the main program ends with that same register, the number reaches the shell as the exit status of the process:
IDENTIFICATION DIVISION.
PROGRAM-ID. MAINP.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-LIMIT PIC 9(5) VALUE 120.
PROCEDURE DIVISION.
CALL "CHECK-IT" USING WS-LIMIT.
DISPLAY "return-code " RETURN-CODE.
STOP RUN.
END PROGRAM MAINP.
IDENTIFICATION DIVISION.
PROGRAM-ID. CHECK-IT.
DATA DIVISION.
LINKAGE SECTION.
01 L-LIMIT PIC 9(5).
PROCEDURE DIVISION USING L-LIMIT.
IF L-LIMIT IS GREATER THAN 100
MOVE 12 TO RETURN-CODE
ELSE
MOVE 0 TO RETURN-CODE
END-IF.
GOBACK.
END PROGRAM CHECK-IT.
cobc -x -free -Wall -o rc rc.cob
./rc
echo $?
return-code +000000012
12
The caller printed the register and the shell printed the exit status, and both are 12. The register is formatted as a signed number of nine digits when it is displayed, which is why the first line reads +000000012.
Two properties make this register convenient and dangerous. Every program of the run shares it, so a subprogram that sets it and a caller that ignores it still change the exit status of the process. And nothing resets it between calls: a callee that sets 12 on one path and forgets it on the next leaves the old value for the shell.
The status as a parameter
The version that port to another compiler without a thought puts the status in the parameter list, where it is an ordinary linkage item and the caller decides what to do with it:
IDENTIFICATION DIVISION.
PROGRAM-ID. MAINP.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-LIMIT PIC 9(5) VALUE 120.
01 WS-STATUS PIC 9(2) VALUE 0.
PROCEDURE DIVISION.
CALL "CHECK-IT" USING WS-LIMIT WS-STATUS.
DISPLAY "status " WS-STATUS.
EVALUATE WS-STATUS
WHEN 0 DISPLAY "accepted"
WHEN 12 DISPLAY "limit above 100"
WHEN OTHER DISPLAY "unknown status " WS-STATUS
END-EVALUATE.
MOVE WS-STATUS TO RETURN-CODE.
STOP RUN.
END PROGRAM MAINP.
IDENTIFICATION DIVISION.
PROGRAM-ID. CHECK-IT.
DATA DIVISION.
LINKAGE SECTION.
01 L-LIMIT PIC 9(5).
01 L-STATUS PIC 9(2).
PROCEDURE DIVISION USING L-LIMIT L-STATUS.
IF L-LIMIT IS GREATER THAN 100
MOVE 12 TO L-STATUS
ELSE
MOVE 0 TO L-STATUS
END-IF.
GOBACK.
END PROGRAM CHECK-IT.
cobc -x -free -Wall -o stat stat.cob
./stat
echo $?
status 12
limit above 100
12
The caller translates the number into a sentence and then decides on the exit status itself. That division of work is what a batch job wants: the subprogram says what happened, the main program decides whether the step failed and what the scheduler should see.
RETURNING, and what 3.2 does with it
The standard form of the same idea is a RETURNING phrase on the CALL and on the PROCEDURE DIVISION of the callee. Its first rule is that the returning item has to be a linkage item, and this build says so:
IDENTIFICATION DIVISION.
PROGRAM-ID. MAINP.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-CODE PIC 9(2) VALUE 0.
01 WS-LIMIT PIC 9(5) VALUE 120.
PROCEDURE DIVISION.
CALL "CHECK-IT" USING WS-LIMIT RETURNING WS-CODE.
DISPLAY "code " WS-CODE.
STOP RUN.
END PROGRAM MAINP.
IDENTIFICATION DIVISION.
PROGRAM-ID. CHECK-IT.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-CODE PIC 9(2) VALUE 0.
LINKAGE SECTION.
01 L-LIMIT PIC 9(5).
PROCEDURE DIVISION USING L-LIMIT RETURNING WS-CODE.
IF L-LIMIT IS GREATER THAN 100
MOVE 12 TO WS-CODE
ELSE
MOVE 0 TO WS-CODE
END-IF.
GOBACK.
END PROGRAM CHECK-IT.
cobc -x -free -Wall -o retn2 retn2.cob
retn2.cob:19: error: RETURNING item is not defined in LINKAGE SECTION
17 | LINKAGE SECTION.
18 | 01 L-LIMIT PIC 9(5).
19 > PROCEDURE DIVISION USING L-LIMIT RETURNING WS-CODE.
20 | IF L-LIMIT IS GREATER THAN 100
21 | MOVE 12 TO WS-CODE.
Move the field into the linkage section and the build succeeds, with a warning that says everything about what comes next:
IDENTIFICATION DIVISION.
PROGRAM-ID. MAINP.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-CODE PIC 9(2) VALUE 0.
01 WS-LIMIT PIC 9(5) VALUE 120.
PROCEDURE DIVISION.
CALL "CHECK-IT" USING WS-LIMIT RETURNING WS-CODE.
DISPLAY "code " WS-CODE.
STOP RUN.
END PROGRAM MAINP.
IDENTIFICATION DIVISION.
PROGRAM-ID. CHECK-IT.
DATA DIVISION.
LINKAGE SECTION.
01 L-LIMIT PIC 9(5).
01 L-CODE PIC 9(2).
PROCEDURE DIVISION USING L-LIMIT RETURNING L-CODE.
IF L-LIMIT IS GREATER THAN 100
MOVE 12 TO L-CODE
ELSE
MOVE 0 TO L-CODE
END-IF.
GOBACK.
END PROGRAM CHECK-IT.
cobc -x -free -Wall -o retn retn.cob
./retn
echo $?
ret.cob:22: warning: program RETURNING is not implemented [-Wpending]
20 | 01 L-LIMIT PIC 9(5).
21 | 01 L-CODE PIC 9(2).
22 > PROCEDURE DIVISION USING L-LIMIT RETURNING L-CODE.
23 | IF L-LIMIT IS GREATER THAN 100
24 | MOVE 12 TO L-CODE
Segmentation fault (core dumped)
139
The warning [-Wpending] says the feature is not implemented, and the run of the built program ends with a segmentation fault and exit status 139: the call wants a return slot the runtime does not have. A program that has to report a result in this compiler passes a parameter, as the previous section does, or sets RETURN-CODE.
The two working forms are not a workaround that will age badly: nearly every production COBOL call in the world uses a status parameter or RETURN-CODE, because that is what the compilers of the 1970s and 1980s implemented.
Exercises
- Set RETURN-CODE to 12 in the callee and then call a second subprogram that never touches the register. Which value does the caller read?
- Change the limit of the first program to 50 and read both the display and the shell status.
- Add a third status to the EVALUATE of the second program for a limit of zero, and a branch in the callee for it.
- Build the RETURNING program without -Wall. Is the warning gone, and does the run still crash?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What is RETURN-CODE?
Answer
A special register shared by the programs of the run, which becomes the exit status
The caller read +000000012 and the shell saw 12.
-
Which value does RETURN-CODE hold after a call that never sets it?
Answer
Whatever the previous program left there
The register is shared and nothing resets it between calls.
-
What does the caller of the second program do with the status parameter?
Answer
It prints a message for it and then copies it to RETURN-CODE
The display, the EVALUATE and the MOVE to the register are the three steps.
-
What does this compiler do with PROCEDURE DIVISION RETURNING?
Answer
It builds with -Wpending and the run crashes with a segmentation fault
The warning says not implemented and the run ended with exit status 139.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-L PIC 9(5) VALUE 50. 01 W-S PIC 9(2) VALUE 0. PROCEDURE DIVISION. CALL "Q5SUB" USING W-L W-S. DISPLAY W-S. STOP RUN. END PROGRAM Q5. IDENTIFICATION DIVISION. PROGRAM-ID. Q5SUB. DATA DIVISION. LINKAGE SECTION. 01 L-L PIC 9(5). 01 L-S PIC 9(2). PROCEDURE DIVISION USING L-L L-S. IF L-L IS GREATER THAN 100 MOVE 12 TO L-S ELSE MOVE 0 TO L-S END-IF. GOBACK. END PROGRAM Q5SUB.Answer
00
The limit is below 100, so the callee sets the status to zero, and the two-digit field shows 00.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-S PIC 9(2) VALUE 7. PROCEDURE DIVISION. DISPLAY W-S. MOVE 0 TO W-S. DISPLAY W-S. STOP RUN. END PROGRAM Q6.Answer
07 then 00
The two displays run around the move that clears the field.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-C PIC 9(2) VALUE 12. PROCEDURE DIVISION. EVALUATE W-C WHEN 0 DISPLAY "ok" WHEN 12 DISPLAY "limit" WHEN OTHER DISPLAY "other" END-EVALUATE. STOP RUN. END PROGRAM Q7.Answer
limit
The second branch matches the value 12 before WHEN OTHER is reached.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-N PIC 9 VALUE 0. PROCEDURE DIVISION. CALL "Q8SUB". DISPLAY W-N. STOP RUN. END PROGRAM Q8. IDENTIFICATION DIVISION. PROGRAM-ID. Q8SUB. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-N PIC 9 VALUE 5. PROCEDURE DIVISION. DISPLAY "sub " W-N. GOBACK. END PROGRAM Q8SUB.Answer
sub 5 then 0
Each program has its own working storage, so the counter of the caller stays zero.
-
Why does a batch job prefer a status parameter over RETURN-CODE?
Answer
The caller decides the exit status, and a shared register cannot be forgotten by accident
The second program translated the number and then moved it to the register itself.
-
A callee sets RETURN-CODE to 12 on one path only. What does the caller see on the other path?
Answer
Whatever the register held before, often the value of an earlier call
Nothing resets the register between calls, which is why the exercise at the end of the page asks about it.
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