Using Special Variables for debugging

As mentioned earlier, REXX language has three special variables — RC, SIGL, and RESULT. These variables are set by the system during execution of commands and will hold the information on command execution.

If the system did not set a value, a special variable displays its name, as do other variables in REXX. The special variables RC and SIGL can be used to help diagnose problems within execs.

Return Code RC:

RC stands for return code and is set every time a command is issued. When a command ends without error, RC is usually set to 0. When a command ends in error, RC is set to whatever return code is assigned to that error.

For example, the when an incorrect LISTDS command is issued, RC will hold a non-zero value denoting that the execution of statement has failed.

"LISTDS ?"
SAY 'RETURN CODE FROM THE COMMAND IS' RC

Note:

The value of RC is set by every command and might not remain the same for the duration of an exec. When using RC, make sure the variable is accessed as soon as the command is executed.

The above exec results in the following

MISSING DATA SET NAME
INVALID KEYWORD, ?
RETURN CODE FROM THE COMMAND IS 12
***

SIGL:

The SIGL special variable is used in connection with a transfer of control within an exec because of a function, or a SIGNAL or CALL instruction. When the language processor transfers control to another routine or another part of the exec, it sets the SIGL special variable to the line number from which the transfer occurred.

If the called routine itself calls another routine, SIGL is reset to the line number from which the most recent transfer occurred.

In the below example, SUBR is called from line number 5. When the SIGL variable is accessed in SUBR it will hold a value of 5.

Example:

000001	/* REXX */
000002	/* REXX TO DEMONSTRATE THE USAGE OF SIGL COMMAND */
...
000005	CALL SUBR
...
000008
000009	SUBR:
000010	SAY 'WE CAME HERE FROM LINE' SIGL   /* SIGL is set to 5 */
000011	RETURN

SIGL and the SIGNAL ON ERROR instruction can be used in conjunction to determine the command which caused an error and the type of error. When SIGNAL ON ERROR is included in an exec, any host command that returns a nonzero return code causes transfer of control to a routine named "ERROR". The error routine runs regardless of other actions that would normally take place, such as the display of error messages.

Consider the following example,

00001/* REXX */
00002/* REXX TO DEMONSTRATE THE USAGE OF SIGNAL ON ERROR */
00003SIGNAL ON ERROR
00004"ALLOC DA(new.data) LIKE(old.data)"
...
00008"LISTDS ?"
...
00011EXIT
00012ERROR:
00013SAY 'The return code from the command on line' SIGL 'is' RC

Output:

The return code from the command on line 8 is 12.

If you have any doubts or queries related to this chapter, get them clarified from our Mainframe experts on ibmmainframer Community!