NetRexx

Trace instruction

   trace tracesetting;

   where tracesetting is one of:

     all
     methods
     off
     results

The trace instruction is used to control the tracing of the execution of NetRexx methods, and is primarily used for debugging.

One trace instruction may appear before the first method in a class, in which case it sets the initial trace setting for all methods in the class (the default is off). Within methods, the trace instruction changes the trace setting when it is executed, and affects the tracing of all clauses in the method which are then executed (until changed by a later trace instruction).

trace all

All clauses (except null clauses without commentary) which are in methods and which are executed after the trace instruction will be traced. If trace all is placed before the first method in the current class, the method instructions in the class, together with the values of the arguments passed to each method, will be traced when the method is invoked (that is, trace all implies trace methods).

trace methods

All method clauses in the class will be traced when the method they introduce is invoked, together with the values of the arguments passed to each method; no other clauses, or results, will be traced. The trace methods instruction must be placed before the first method in the current class (as otherwise it would have no effect).

trace off

Turns tracing off; no following clauses, or results, will be traced.

trace results

All clauses (except null clauses without commentary) which are in methods and which are executed after the trace instruction will be traced, as though trace all had been requested. In addition, the results of all expression evaluations and any results assigned to a variable by an assignment, loop, or parse instruction are also traced.

If trace results is placed before the first method in the current class, the method instructions in the class will be traced when the method is invoked, together with the values of the arguments passed to each method.

Notes:

1. Tracing of clauses shows the data from the source of the program, starting at the first character of the first token of the clause and including any commentary from that point until the end of the clause.
2. When a loop is being traced, the loop clause itself will be traced on every iteration of the loop, as indicated by the programmer's model; the end clause is only traced once, when the loop completes normally.
3. With trace results, an expression is not traced if it is immediately used for an assignment (in an assignment instruction, or when the control variable is initialized in a loop instruction). The assignment will trace the result of the expression.
4. Trace output is written to an implementation-defined output stream (typically the 'standard error' output stream, which lets it be redirected to a destination separate from the default destination for output which is used by the say instruction).
5. In some implementations, the use of trace instructions may substantially increase the size of classes and the execution time of methods affected by tracing.[1] 
6. With some implementations it may be possible to switch tracing on externally, without requiring modification to the program.

The format of trace output

Trace output is either clauses from the program being traced, or results (such as the results from expressions).

The first clause or result traced on any line will be preceded by its line number in the program; this is right-justified in a space which allows for the largest line number in the program, plus one blank. Following clauses or results from the same line are preceded by white space of the same width; however, any change of line number causes the line number to be included.

Clauses that are traced will be displayed with the formatting (indention) and layout used in the original source stream for the program, starting with the first character of the first token of the clause.

Results (if requested) are converted to a string for tracing if necessary, are not indented, and have a double quote prefixed and suffixed so that leading and trailing blanks are apparent; if, however, the result being traced is null then the string '[null]' is shown (without quotes). For results with an associated name (the values assigned to local variables, method arguments, or properties in the current class), the name of the result precedes the data, separated by a single blank.

For clarity, implementations may replace 'control codes' in the encoding of results (for example, EBCDIC values less than '\x40', or Unicode values less than '\x20') by a question mark ('?').

All lines displayed during tracing have a three character tag to identify the type of data being traced. This tag follows the line number (or the space for a line number), and is separated from the line number by a single blank. The traced clause or result follows the tag, after another blank. The identifier tags may be:

*=*

identifies the first line of the source of a single clause, i.e., the data actually in the program.

*-*

identifies a continuation line from the source of a single clause. Continuations may be due to the use of a continuation character or to the use of a block comment which spans more than one line.

>a>

Identifies a value assigned to a method argument of the current method. The name of the argument is included in the trace.

>p>

Identifies a value assigned to a property. The name of the property is included in the trace if the property is in the current class.

>v>

Identifies a value assigned to a local variable in the current method. The name of the variable is included in the trace.

>>>

Identifies the result of an expression evaluation that is not used for an assignment (for example, an argument expression in a method call).

+++

Reserved for error messages that are not supplied by the environment underlying the implementation.

Examples:
If the following instructions, starting on line 53 of a 120-line program, were executed:

  trace all
  if i=1 then say 'Hello'
         else say 'i<>1'
  say -
   'A continued line'

    54 *=* if i=1
       *=*        then
       *=*             say 'Hello'
    56 *=* say -
    57 *-*  'A continued line'

  trace results
  number=1/7
  parse number before '.' after

   2 *=* number=1/7
     >v> number "0.142857143"
   3 *=* parse number before '.' after
     >v> before "0"
     >v> after "142857143"

Footnotes:
[1]