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