2.4.22 The TRACE Instruction TRACE [ number | setting | [ VALUE ] expr ] ; setting = A | S | C | E | F | I | L | N | O | R | S The TRACE instruction is used to set a tracing mode. Depending on the current mode, various levels of debugging information is displayed for the programmer. Also interactive tracing is allowed, where the user can re-execute clauses, change values of variables, or in general, execute REXX code interactively between the statements of the REXX script. If setting is not specified, then the default value N is assumed. If the second token after TRACE is VALUE, then the remaining parts of the clause is interpreted as an expression, which value is used as the trace setting. Else, if the second token is either a string of a symbol, then it is taken as the trace setting; and a symbol is taken literally. In all other circumstances, whatever follows the token TRACE is taken to be an expression, which value is the trace setting. If a parameter is given to the TRACE instruction, and the second token in the instruction is not VALUE, then there must only be one token after TRACE, and it must be either a constant string or a symbol (which is taken literally). The value of this token can be either a whole number or a trace setting. If is it a whole number and the number is positive, then the number specifies how many of interactive pauses to skip. This assumes interactive tracing; if interactive tracing is not enabled, this TRACE instruction is ignored. If the parameter is a whole, negative number, then tracing is turned off temporarily for a number of clauses determined by the absolute value of number. If the second token is a symbol of string, but not a whole number, then it is taken to be one of the settings below. It may optionally be preceded by one or more question mark (?) characters. Of the rest of the token, only the first letter matter; this letter is translated to upper case, and must be one of the following: [A] (All) Traces all clauses before execution. [C] (Commands) Traces all command clauses before execution. [E] (Errors) Traces any command that would raise the ERROR condition (whether enabled or not) after execution. Both the command clause and the return value is traced. [F] (Failures) Trances any command that would raise the FAILURE condition (whether enabled or not) after execution. Both the command clause and the return value is traced. [I] (Intermediate) Traces not only all clauses, but also traces all evaluation of expressions; even intermediate results. This is the most detailed level of tracing. [L] (Labels) Traces the name of any label clause executed; whether the label was jumped to or not. [N] (Normal or Negative) This is the same as the Failure setting. [O] (Off) Turns off all tracing. [R] (Results) Traces all clauses and the results of evaluating expressions. However, intermediate expressions are not traced. [S] (Scan) Traces all clauses from the current position in the script, until the end of the file, in sequence. However, it does not execute any of the clauses. When the end of the program is reached, the interpreter exits. The Errors and Failures settings are not influenced by whether the ERROR or FAILURE conditions are enabled or not. These TRACE settings will trace the command and return value after the command have been executed, but before the respective condition is raised. The levels of tracing might be set up graphically, as in the figure below. An arrow indicates that the setting pointed to is a superset of the setting pointed from. /—> Failures —> Errors —> Commands Off \ \————-> Labels ———————-> All —> Results —> Intermediate Hierarchy of TRACE settings According to this figure, Intermediate is a superset of Result, which is a superset of All. Further, All is a superset of both Commands and Labels. Commands is a superset of Errors, which is a superset of Failures. Both Failure and Labels are supersets of Off. Actually, Command is strictly speaking not a superset of Errors, since Errors traces after the command, while Command traces before the command. Scan is not part of this diagram, since it provides a completely different tracing functionality. Note that Scan is part of TRL1, but was removed in TRL2. It is not likely to be part of newer REXX interpreters.
PREV NEXT