Revised November 2018
++PRAGMA TRACE_BEGIN {optionlist}
++PRAGMA TRACE_END
++PRAGMA TRACE_OPTIONS {optionlist}
TRACE_BEGIN and TRACE_END may be used to bracket a section of code for which automatic TRACE.PRINT statements will be generated after each program statement. Each auto-generated trace will consist of two lines: first the source code, then the trace of the variables in that statement. Note that not all statements will be traced; primarily it is limited to those statements which operate on variables. Also note that the trace generally occurs after the statement execution, which means that function and procedure call statements show up in the trace output after the routine returns. IF statements are an exception in that they get traced prior to execution (so you can see the IF statement regardless of whether the condition is true or false).
The TRACE_OPTIONS pragma only establishes default options for subsequent manually typed xxxxx.PRINT and xxxxx.PAUSE statements, except for those which already include their own explicit options. Note that the optionlist on the TRACE_BEGIN statement also establishes the default options, in addition to activating the auto tracing.
The optionlist consists of the following four fields. Each field is itself optional, although in order to specify a subsequent field, you must specify the prior ones. The parentheses are optional if only the dbglvl field is specified; otherwise they are mandatory.
dbglvl
Sets the debug level for the statement; the higher the level, the higher the corresponding DEBUG system variable must be in order to activate the statement. See SET.LIT DEBUG <options> for details on setting the runtime dbglvl. The default dbglvl is 1, and requiring SET DEBUG {1} to enable.
tags
A quoted literal string consisting of comma-delimited symbols to be associated with each xxxxx.PRINT or xxxxx.PAUSE statement. Use the SET.LIT DEBUG <options> command at runtime to specify tags to filter the trace output by. Note that the current program and SBX names are implicitly added to the tags list.
prefix
A quoted literal string which, if specified, is inserted at the start of each xxxxx.PRINT / xxxxx.PAUSE statement, typically used to specify macros like $#, $T, $P, $L, etc. It comes in handy in situations where you already have a lot of xxxxx.PRINT statement in the program, but are having trouble identifying them in the trace output. Rather than manually modifying each statement to include additional contextual identifiers, you could simply specify ++PRAGMA TRACE_OPTIONS (0,"","$L") to insert the location counter into each trace.
tokens
A quoted list of tokens—typically variables—to be traced. If specified, only lines containing one of those tokens/variables will be auto-traced.
Example
++PRAGMA TRACE_BEGIN (5,"tag1","$#","qty,TOTAL,sku")
Following the above pragma, only lines containing "qty", "TOTAL", or "sku" will be set up by the compiler for auto-tracing. Whether the tracing will actually occur at runtime will be dependent on options established at runtime via the SET.LIT DEBUG <options> command. The debug level will need to be set to at least 5, and/or the tag value "tag1" will need to be set.
Comments
| • | The token matching is case sensitive, and 'whole word' oriented. So the above would not match the line "qty_1 = QTY / TOTAL2". However, the token XXX in the pragma list will match XXX$, XXX(Y), and XXX.Y. |
| • | Tokens will also match anywhere in the source line—i.e. within string literals and even comments. |
| • | The trace token filtering is handled entirely by the compiler. |
| • | TRACE_BEGIN / END blocks can be nested to 38 levels. Any unterminated TRACE_BEGIN block will be automatically terminated at the end of each source file module ro function. Consequently, to trace an entire include module, you could insert just the ++PRAGMA TRACE_BEGIN at the top. |
| • | Unlike the trace.print statement, if no optionlist is specified, the default dbglvl is 1, meaning that the traces are disabled by default, requiring some form of SET DEBUG to enable. |
See Also
History
2018 August, A-Shell 6.5.1644: • Specify a list of tokens to be traced. • TRACE_BEGIN / END blocks can now be nested to 38 levels. Any unterminated TRACE_BEGIN block will be automatically terminated at the end of each source file module. Consequently, to trace an entire include module, you could insert just the ++PRAGMA TRACE_BEGIN at the top.
2018 July, A-Shell 6.5.1639: Added to A-Shell.
