The COBOL special register RETURN-CODE can be used for communication purposes between separately compiled COBOL programs of a run unit. The special register exists only once in the program system and is defined internally as a four-digit binary data item (PIC S9(9) COMP-5 SYNC).
RETURN-CODE can be interrogated or modified as required at run time by the separately compiled programs. On termination of the program run, the runtime system checks whether RETURN-CODE is zero. If this is not the case, the error message COB9119 (if the COBOL return code > 0) or COB9128 (if the user return code > 0) is output. If the program was called within a procedure, the program branches to the next SET-JOB-STEP, EXIT-JOB, LOGOFF, CANCEL-PROCEDURE, END-PROCEDURE or EXIT-PROCEDURE command.
When a COBOL subprogram is exited, the value of the special register RETURN-CODE is also loaded in registers 0 and 1. This makes the value available to the calling program in the form of a function value, in accordance with the ILCS conventions.
In order to use a function value from a C program, the calling COBOL program must be compiled with the control statement RETURN-CODE=FROM-ALL-SUBPROGRAMS for the RUNTIME-OPTIONS option, or with the COMOPT operand ACTIVATE-XPG4-RETURNCODE=YES (Attention: the function value cannot be obtained with the “RETURNING” specification in the CALL statement).
To avoid the abnormal termination of the program, the user must ensure that RETURN-CODE contains the value 0 before the STOP RUN statement is reached.