TRACE [symbol] TRACE "string" TRACE VALUE expression The symbol, string constant or expression is evaluated (the VALUE keyword may be omitted if the expression does not start with a symbol or a string constant). It must evaluate to a word consisting of zero or more question marks, followed by an optional letter, followed by an optional string of characters. Each question mark at the start of the string toggles the `interactive tracing' mode (see below), and the following letter, if any, is translated to upper case and must be one of the following: A (All): all clauses are traced before execution C (Commands): all commands to the environment are traced before execution, together with the actual string passed to the environment. If the command results in a non-zero return code, then the return code is traced after execution. E (Error): Any command to the environment resulting in an error (i.e. non-zero return code) is traced after execution, together with the return code F (Failure): Any command to the environment resulting in failure (i.e. negative return code) is traced after execution, together with the return code I (Intermediates): All clauses are traced before execution, and all calculations are traced, including intermediate values evaluated during the calculation. Assignments made by PARSE instructions are also traced. L (Labels): All labels passed during execution are traced N (Normal): the default setting - same as F. O (Off): Nothing is traced, and interactive tracing is also switched off. R (Results): All clauses are traced before execution, and the results from all calculations are traced. Assignments made by PARSE instructions are also traced. If no setting is specified or if the setting is an empty string, then interactive tracing is turned off and tracing is set to "N". When clauses are being traced (i.e. A, R or I), when an INTERPRET command is traced, the actual string being interpreted is also traced. When an END command is traced, the source statement to which the END corresponds is also traced. A program may be made to trace itself during execution by signalling it with SIGQUIT (on the Suns this can be done by pressing "control \"). When this signal is received, the tracing mode switches to "?i". If a SIGQUIT is received whilst in interactive tracing mode and if an interruption has already been received but not handled, the program exits immediately (as is the case when SIGQUIT is not handled). This feature exists mainly to stop the interpreter in case of a bug. A program may be made to trace itself when execution starts by using the "-t" commandline flag (see the invocation section for details). Interactive tracing In interactive trace mode, all TRACE instructions passed in the program are ignored and the interpreter will pause after tracing each clause, label, command or return code (as appropriate for the trace setting). The interpreter prompts for input with the string ">trace>". If an empty line is entered (without spaces), execution of the program continues normally until the next event which is traced. If a line of REXX is entered, then that line is interpreted with tracing set to "E". If the line calls a program, then TRACE instructions in that program are ignored. If the line itself uses the TRACE instruction, then the trace setting is altered accordingly and execution of the program will continue after the input line has been interpreted. If the input line does not contain a TRACE instruction, then when it has been interpreted the prompt will reappear for more input. If an error occurs during interpretation of the input line, a message is displayed and the prompt reappears (unless the command executed a TRACE instruction). The error does not cause the program to exit, and no signalling takes place (unless the error occurred in a program which was called by the input line and which contains its own SIGNAL ON xxx command). Commands to the environment within the string will not set the variable RC, but will have non-zero return codes traced. All condition traps are turned off during interpretation of the string. It is possible to make the interpreter change tracing and also prompt for more input by using the built-in TRACE function rather than the TRACE instruction, for example: call trace r sets the `results' tracing mode (whilst keeping interactive mode) without continuing execution of the program. The interactive tracing mode is useful for the following purposes (and others): - single-stepping through a program (use trace ?a) - setting breakpoints (use trace ?l and put a label at the breakpoint) - examining or changing variables during execution. The input line is interpreted in exactly the same way as with the INTERPRET command, and so the same restrictions apply (e.g. DO and END instructions etc must be matched properly). BUG:The following also applies, however: - some of the source information is lost, so any PARSE SOURCE instruction in the line will have the calling method and the calling name replaced by "TRACE" (this does not apply to PARSE SOURCE instructions within programs that may be called by the input line). If the input line transfers control by a SIGNAL instruction, then control is immediately transferred to the target instruction and it is executed before tracing resumes. If the input line contains a RETURN or EXIT instruction, then execution returns to the caller and continues to the end of the current statement. The return may cause a change in the tracing mode, since this is saved across function calls. However, if interactive tracing is still in effect, then tracing will resume at the next instruction. NOTE:If the interpreter has a controlling terminal (that is, "/dev/tty" can be opened when the interpreter initialises), then the trace prompt will be written to the terminal, and input will be read from the terminal. Otherwise, stderr and stdin are used respectively. If an error occurs during a command which was typed in interactive trace mode, then the error message will be written to the terminal. However, all normal input and output use stdin and stdout, while trace output is written to the requested file (see OPTIONS). In particular, if tracing has been redirected, then no trace output will appear on the terminal. Therefore it is not a good idea to redirect tracing when interactive tracing will be used. BUG: Interactive tracing is not recursive, i.e. if, during interactive tracing, a line is entered such as: trace i;say a+b then the tracing of "say a+b" (and other statements following the TRACE instruction) will not be interactive, even though the interactive tracing mode is (in theory) still in operation. TRACE output Each line of trace output is preceded by three characters which identify the type of trace output. Any clause or command traced will be indented according to its logical depth of nesting. Results (or intermediate values) will be indented a further two spaces, and have leading and trailing quotes added. The line numbers of source statements and labels are displayed before the three-character prefix. An interpreted instruction or a command about to be executed will be displayed without a line number. The three-character prefixes are: +++ A trace message (an error message, or the return code from a command) *-* A source statement or label (exactly as it appears in the source). *,* A source statement which is continued from the previous line. *~* The result of evaluating an expression which is either a command to be passed to the environment or the parameter of an INTERPRET instruction. >>> The result of an expression displayed in "trace r", or the value assigned to a variable during parsing or during update of the control variable of a repetitive DO loop. >.> The value `assigned' to a placeholder (dot) during parsing. The following prefixes are used during TRACE I: >V> The contents of a variable >L> a literal (that is, a constant symbol or number, an uninitialised variable, or a string/hex/binary constant) >F> The result of applying a function >P> The result of applying a prefix operator >O> The result of applying a (binary) operator >C> The name of a compound variable (after substitution and before use). The trace setting is saved across function calls, so that if tracing is switched on or off during a function, the previous setting is restored when the function returns. This means that: - if a function is known to work, then "trace off" may be placed at the start. When a program is being traced, tracing is switched off when the function is entered, and back on when the function returns. - if a function is known not to work, then a trace instruction placed at the start of the function will switch tracing on only for the duration of the function call.