When you encounter an error in a program, there are several ways to locate the error.
The TRACE instruction has many options for various types of tracing, including C for commands and E for errors.
After TRACE C, the language processor traces each command before execution, then executes it and sends the return code from the command to the current terminal output device. For more information on specifying the current terminal output device, refer to the SET TERMOUT command.
When you specify TRACE E in a program, the language processor traces any host command that results in a nonzero return code after execution and sends the return code from the command to the terminal.
If a program includes TRACE E and issues an incorrect command, the program sends error messages ,the line number, the command, and the return code from the command to the output stream.
For more information about the TRACE instruction, see section TRACE.
The REXX language has three special variables: RC, SIGL, and RESULT. REXX/CICS sets these variables during particular situations and you can use them in an expression at any time. If REXX/CICS did not set a value, a special variable has the value of its own name in uppercase, as do other variables in REXX. You can use two special variables, RC and SIGL, to help diagnose problems within programs.
RC stands for return code. The language processor sets RC every time a program issues a command. When a command ends without error, RC is usually 0. When a command ends in error, RC is whatever return code is assigned to that error.
The RC variable can be especially useful in an IF instruction to determine which path a program should take.
The language processor sets the SIGL special variable in connection with a transfer of control within a program because of a function, a SIGNAL or a CALL instruction. When the language processor transfers control to another routine or another part of the program, it sets the SIGL special variable to the line number from which the transfer occurred. (The line numbers in the following example are to aid in discussion after the example. They are not part of the program.)
1 /* REXX */
2 :
3 CALL routine
4 :
5
6 routine:
7 SAY 'We came here from line' SIGL /* SIGL is set to 3 */
8 RETURN
If the called routine itself calls another routine, SIGL is reset to the line number from which the most recent transfer occurred.
SIGL and the SIGNAL ON ERROR instruction can help determine which command caused an error and what the error was. When SIGNAL ON ERROR is in a program, any host command that returns a nonzero return code causes a transfer of control to a routine named error. The error routine runs regardless of other actions that would usually take place, such as the transmission of error messages.
For more information about the SIGNAL instruction, see section SIGNAL.
The interactive debug facility lets a user control the execution of a program. The language processor reads from the terminal, and writes output to the terminal.
To start interactive debug, specify ? before the option of a TRACE instruction, for example: TRACE ?A. There can be no blank(s) between the question mark and the option. Interactive debug is not carried over into external routines that are called but is resumed when the routines return to the traced program.
After interactive debug starts, you can provide one of the following during each pause or each time the language processor reads from the input stream.
TRACE L /* Makes the language processor pause at labels only */
The input could be an assignment instruction. This could change the flow of a program, by changing the value of a variable to force the execution of a particular branch in an IF THEN ELSE instruction. In the following example, RC is set by a previous command.
IF RC = 0 THEN
DO
instruction1
instruction2
END
ELSE
instructionA
If the command ends with a nonzero return code, the ELSE path is taken. To force taking the first path, the input during interactive debug could be:
RC = 0
You can end interactive debug in one of the following ways:
+++ Interactive trace. TRACE OFF to end debug, ENTER to continue. +++
The question mark prefix before a TRACE option can end interactive debug as well as beginning it. The question mark reverses the previous setting (on or off) for interactive debug. Thus you can use TRACE ?R within a program to start interactive debug, and provide input of another TRACE instruction with ? before the option to end interactive debug but continue tracing with the specified option.
REXX/CICS provides the ability to route trace output to a file. The REXX command SET TERMOUT routes linemode output (such as SAY and TRACE output) to a file instead of, or in addition to, the current terminal device.