REXX provides several tools for determining where problems are within the REXX program. In this chapter the following topics are covered:
Using the TRACE Instruction and the TRACE Function Using the Trace REXX (TRCREX) Command.
For more information on other REXX tools for identifying problems within a REXX program, see the REXX/400 Reference.
Using the TRACE Instruction and the TRACE Function
The TRACE instruction provides you with a powerful tool for determining errors. TRACE lets you see how expressions are being evaluated while the program is actually running.
The TRACE instruction can be placed anywhere within a REXX program where you want more specific information about how the program is being interpreted.
When a TRACE instruction is being interpreted, the first letter of the second word determines the type of tracing, and the remainder of the second word is ignored. The following are the most commonly used trace settings. For more information on tracing and the other trace settings, see the REXX/400 Reference.
Trace Intermediates As each expression is evaluated, the result of each operation, the Intermediate results, is shown on the display.
Trace Results When each expression has been evaluated, the final result is shown on the display.
Trace Normal Only commands that would raise the failure condition are displayed, along with their return code. This is the default setting.
Trace Errors Commands that would raise an error or failure are displayed, along with their return code.
The TRACE function returns the current trace settings, when used without arguments. When an argument is specified, the trace setting is changed to the specified argument, and the previous setting is returned.
In order for TRACE results to be shown on the display, the character identifier (CHRID) must match the character set and code page (CCSID) of the REXX source file member being traced.
Using Interactive Tracing
Interactive tracing is turned on and off by placing a question mark immediately in front of the TRACE setting. For example, TRACE ?R will provide interactive tracing of results. Interactive tracing lets you examine each clause, one at a time, and continue interpretation by pressing the Enter key. Interactive tracing causes the program to pause after it interprets most instructions that result in trace output. The exceptions include SIGNAL, CALL, and reiterations of DO loops.
If interactive tracing is turned on and another TRACE instruction is encountered, the new trace setting is ignored. Unlike the TRACE instruction, the TRACE function will change the current trace setting when it is encountered during interactive tracing.
When interactive tracing is turned on, you are prevented from overriding STDIN. Note: Do not turn interactive tracing on for REXX programs which override STDIN.
Using Trace Settings
The following example lets you experiment with different trace settings. By entering the particular trace setting you are interested in, you can see how tracing works differently with each option.
/\ This program performs a variety of operations. The different \/ /\ trace options are used in this program to show how they differ. \/ SAY 'Enter trace option to use'
PULL traceopt
TRACE VALUE traceopt one = 1
SAY 'The maximum of 1 and -2 is' max(one,-2) "SNDMSG('Hello') TOUSR(\WRONG)"
Trace Output for the TRACE Intermediates Setting: If you choose the intermediates option when you run this program, the trace output looks like the following:
à
ð
i
5 \-\ one = 1; >L> "1"
6 \-\ Say 'The maximum of 1 and -2 is' MAX(one, - 2); >L> "The maximum of 1 and -2 is"
>V> "1" >L> "2" >P> "-2" >F> "1"
>O> "The maximum of 1 and -2 is 1" The maximum of 1 and -2 is 1
7 \-\ 'SNDMSG('Hello') TOUSR(\WRONG)'; >L> "SNDMSG('Hello') TOUSR(\WRONG)" +++ RC(CPFððð1)
Press ENTER to end terminal session.
==> ___________________________________________________________________ _______________________________________________________________________
3=Exit F4=End of File F6=Print F9=Retrieve F17=Top 18=Bottom F19=Left F2ð=Right F21=User Window
Trace Output for the TRACE Results Setting: If you choose the results option, the trace output looks like the following:
à
ð
Enter trace option to use r
5 \-\ one = 1; >>> "1"
6 \-\ Say 'The maximum of 1 and -2 is' MAX(one, - 2); >>> "The maximum of 1 and -2 is 1"
The maximum of 1 and -2 is 1
7 \-\ 'SNDMSG('Hello') TOUSR(\WRONG)'; >>> "SNDMSG('Hello') TOUSR(\WRONG)" +++ RC(CPFððð1)
Press ENTER to end terminal session. End of terminal session.
==> ___________________________________________________________________ _______________________________________________________________________
3=Exit F4=End of File F6=Print F9=Retrieve F17=Top 18=Bottom F19=Left F2ð=Right F21=User Window
á
ñ
Trace Output for the TRACE Normal Setting: If you choose the normal option, the trace output looks like the following:
à
ð
Enter trace option to use n
The maximum of 1 and -2 is 1
7 \-\ 'SNDMSG('Hello') TOUSR(\WRONG)'; +++ RC(CPFððð1)
Press ENTER to end terminal session.
==> ___________________________________________________________________ _______________________________________________________________________
3=Exit F4=End of File F6=Print F9=Retrieve F17=Top 18=Bottom F19=Left F2ð=Right F21=User Window
Trace Output for the TRACE Errors Setting: If you choose the errors option, the trace output looks like the following:
à
ð
Enter trace option to use e
The maximum of 1 and -2 is 1
7 \-\ 'SNDMSG('Hello') TOUSR(\WRONG)'; +++ RC(CPFððð1)
Press ENTER to end terminal session.
==> ___________________________________________________________________ _______________________________________________________________________
3=Exit F4=End of File F6=Print F9=Retrieve F17=Top 18=Bottom F19=Left F2ð=Right F21=User Window
á
ñ
Using Trace Settings in Subroutines
When tracing is changed in an internal routine, the previous trace setting is
restored when the internal routine returns to the main program. This lets you easily turn off tracing at the top of your working subroutines while you are still debugging other parts of your program, as shown in the following example.
TRACE I
SAY 'This program calculates 1ð factorial divided by 9 factorial' SAY '(And it does it the hard way.)'
answer = fact(1ð)/ fact(9) SAY 'The answer is' answer EXIT fact: PROCEDURE CALL TRACE O ARG number answer = 1 DO i = 1 TO number answer = answer \ i END RETURN answer
When you run this example, the following will be displayed: Trace Output
2 \-\ SAY 'This program calculates 1ð factorial divided by 9 factorial'; >L> "This program calculates 1ð factorial divided by 9 factorial" This program calculates 1ð factorial divided by 9 factorial
3 \-\ SAY '(And it does it the hard way.)'; >L> "(And it does it the hard way.)" (And it does it the hard way.)
4 \-\ answer = fact(1ð) / fact(9); >L> "1ð" 8 \-\ fact: 8 \-\ Procedure; 9 \-\ CALL TRACE O; >L> "O" >F> "36288ðð" >L> "9" 8 \-\ fact: 8 \-\ Procedure; 9 \-\ CALL TRACE O; >L> "O" >F> "36288ð" >O> "1ð"
5 \-\ SAY 'The answer is' answer; >L> "The answer is"
>V> "1ð"
>O> "The answer is 1ð" The answer is 1ð
6 \-\ EXIT;
Interactive Tracing Example: The following example uses interactive tracing to recover from a command error.
/\ This program has an error in it. Look below to see how \/ /\ interactive tracing can be used to recover from the error. \/ TRACE ?E /\ Set tracing to pause after error commands. \/ SAY 'Tracing will turn on when a command has an error'
user = '\SYSORP' /\ This is misspelled \/
"SNDMSG MSG('Hello') TOUSR("user")" SAY 'Now we are past the error'
Trace Output: When this program is run the error occurs. It is interactively corrected,user = '\SYSOPR'. The=sign causes the last instruction, which is the command, to be run again. With the assignment changed, the program runs.
à
ð
Tracing will turn on when a command has an error 5 \-\ 'SNDMSG MSG('Hello') TOUSR('user')';
+++ RC(CPFððð1)
+++ Interactive trace. "Trace Off" to end debug ENTER to Continue. user = '\SYSOPR'
=
Now we are past the error
Press ENTER to end terminal session.
==> ___________________________________________________________________ _______________________________________________________________________
3=Exit F4=End of File F6=Print F9=Retrieve F17=Top 18=Bottom F19=Left F2ð=Right F21=User Window
á
ñ
Interpreting Trace Results
Output from the TRACE instruction is always written to STDERR. In addition, it is placed in the job log as command (CMD) messages. When you are running a job interactively, all input is also placed in the job log. If you are running in batch mode and the REXX program finds an interactive trace setting, the interactive setting is ignored. For example, if a REXX program issues the instruction TRACE ?I while in batch mode, it is treated as if the instruction was TRACE I.
TRACE Symbols
Output from the TRACE instruction shows a listing with lines prefixed by various symbols. Each symbol identifies actions taken within the program. These symbols can be used to differentiate REXX command (CMD) messages from other
command messages in the job log. User input during interactive tracing is placed in the job log with no prefixes.
\-\ This identifies the source of a single clause, that is, the data actually in the program.
+++ This identifies a trace message. This may be the nonzero return code from a command, the prompt message when interactive debug is entered, an indication of a syntax error when in interactive debug, or the traceback clauses after a syntax error in the program.
>>> This identifies the result of an expression (for TRACE R) or the value assigned to a variable during parsing, or the value returned from a subroutine call.
>.> This identifies the value assigned to a placeholder during parsing
If you are using TRACE Intermediates (TRACE I), the following symbols are also used.
>C> The data traced is the name of a compound variable, traced after substitution and before use, provided that the name had the value of a variable substituted into it.
>F> The data traced is the result of a function call.
>L> The data traced is a literal (string, uninitialized variable, or constant symbol).
>O> The data traced is the result of an operation on two terms. >P> The data traced is the result of a prefix operation.
>V> The data traced is the contents of a variable.
Using the Trace REXX (TRCREX) Command
The TRACE instruction is used within a REXX program. The Trace REXX
(TRCREX) command lets you set interactive tracing of a REXX program from outside that program. See the CL Reference for the complete syntax of this command.
TRCREX sets the trace option which is in effect when interpretation of a REXX program begins. The TRCREX setting remains in effect for all REXX programs until it is changed by issuing anotherTRCREX command or until the job ends.
Since TRCREX turns on interactive tracing of a program, and TRACE instructions in REXX programs are not run during interactive tracing, TRACE instructions may be ignored while aTRCREX setting is in effect. The TRACE function in a program can override any trace setting.
Changing the trace setting in a program will not affect theTRCREX setting. If you run a program with aTRCREX setting in effect, change the TRACE setting in it, and then run another REXX program, the TRCREX setting will be in effect at the start of the second program.