RETURN-CODE Special Register
The RETURN-CODE special register can be used to pass return code information (that is, a numeric value) from a program to its caller (either a calling program or the system).
You can set the RETURN-CODE special register before executing an EXIT PROGRAM, GOBACK, or STOP RUN statement.
01 RETURN-CODE GLOBAL PICTURE S9999 USAGE BINARY VALUE 0
This special register may be used anywhere in a program where a data-item with a data definition of PICTURE S9999 USAGE BINARY is allowed. When used in nested programs, the RETURN-CODE special register is implicitly defined as GLOBAL in the outermost program. When a COBOL subprogram terminates, the contents of the RETURN-CODE special register of the subprogram are transferred into the RETURN-CODE special register of the calling program. When the main COBOL program terminates, and control returns to the operating system, the special register content is returned to the operating system as a user return code.
Note that the main COBOL program must be the first program in an activation group, so normally this COBOL program should not be compiled with option ACTGRP(*CALLER), if you want the contents of the RETURN-CODE special register to be returned as a user return code for the job. The user return code can be retrieved by the calling program by calling API QUSRJOBI with format JOBI0600.
For the first call to a program, the RETURN-CODE special register is initialized to zero, which is the normal return code for successful completion. The field will be re-set to zero on subsequent calls to a program that has been cancelled or which possesses the INITIAL attribute. Otherwise, the RETURN-CODE special register will not be re-set, it will be unchanged from the value it contained after the previous call.
You can specify the RETURN-CODE special register in a function wherever an integer argument is allowed.
For more information on passing return code information, see the IBM® Rational® Development Studio for i: ILE COBOL Programmer's Guide.