# TRACE Statements

> [HTML Version](trace_statements.htm)

_Updated October 2025; see History_

**TRACE.OPEN \{title\}**

**TRACE.PRINT \{(level \{,tags\})\} expr1\{,expr2,...,exprN\}**

**TRACE.PRINT \{(level \{,tags\})\} expr1\{,expr2,...,exprN\}**

**TRACE.CLOSE**

This group of statements is useful for outputting tracing or debugging messages without interfering with the existing screen display or program logic. By default, the messages go to the System Messages Window; see [Opening the Message Window](messagewindow.htm.md). Also see [Debug Settings](debugsettings.htm.md) for other output options: disk file, main window, SBX, etc.

Typically only the TRACE.PRINT statement is needed.  The optional (level,tags) arguments allow the statement to be enabled/disabled at runtime via SET DEBUG statements.  The exprN arguments operate similarly to those in the standard [PRINT](printstatement.htm.md) statement, except that variables will expand out to "variable=\[value\]" (rather than just outputting the value), and the first expression may contain macros (see below).  

TRACE.OPEN is optional, since the TRACE.PRINT and TRACE.PAUSE statements will perform the open operation automatically if necessary.  The only point would be the ability to set the message window title (assuming that is the output option); otherwise it defaults to "A-Shell System Messages".  And TRACE.CLOSE is unnecessary because in the message window case, the user can close it with the mouse, and in the other cases, closing is irrelevant or automatic. 

TRACE.PAUSE is equivalent to TRACE.PRINT except that (assuming trace output is to the System Message window), it causes the application to pause with a message prompting the operator:

<Application paused - Double-click here to resume>

As suggested by the message, the application is then suspended while waiting for the user to double-click the message window. This is intended as alternative to the usual practice of display message boxes which require a click on the OK button to proceed (or the venerable and primitive STOP statement). Note: Ctrl+C will abort the pause and pass the Ctrl+C to the program.

The actual wording of that message and the acknowledgement message when the double-click is received may be customized via the strings 005,002 and 005,003 in sys:sysmsg.xxx.

The optional (_level_, _tags_) arguments(s) provide two overlapping mechanisms for activating specific TRACE statements at run time.  _Level_ sets the minimum DEBUG level to activate the trace, while the _tags_ (one or more string tokens, comma-delimited) provide additional specificity. Both can be set via the [SET DEBUG system command](debugsettings.htm.md). 

The list of expressions  (_expr1, ... exprN_) may be either string expressions or variables.  In the latter case, the output will be expanded to show both the variable name and its value (see the examples below).

A special form of the first expression can be used to enable/disable the Show System Traces option in the System Message window:

TRACE.PRINT "SYSTRACE ON"           \! or "SYSTRACE OFF"

The manual way to do this is to right-click on the message window, click Properties, and then check the System Trace option.) Being able to do this from within a program is sometimes useful when you want to activate certain verbose traces but only for a short time, or starting at the beginning of a session, before you would have a chance to manually open the message window and turn on the traces automatically.

The first expression may also optionally contain any of the following macros:

| **Macro** | **Expands To** |
|------|------|
| \$# | Displays the running message count as a message id number. This applies only when the destination is \$WIN, i.e. the System Message Window, otherwise it is ignored. |
| \$T | Displays the time in hh:mm:ss format, except when destination is a log file that applies its own automatic date/time stamp. |
| \$P | Displays the program name in brackets, e.g. <MYPROG>. If the current context is an SBX, it will be appended to the program name, e.g. <MYPROG:MYSBX>. |
| \$L | Displays the current location counter as a six digit hex number, matching the format used in the LSX file. |
| \$D | Displays the date in dd-mm-yy format, except when destination is a log file that applies its own automatic date/time stamp. |
| \$I | Displays the process ID number. |
| %env% | Environment variable definition. |




Macros, when present, must precede any other output expressions. Typically they are space delimited, in which case the first token that does not start with a \$ or % cancels the macro processing for the remainder of the arguments. Alternatively, the macros can be comma delimited, which may be useful when outputting to a custom log file in CSV format.  In that case the first comma-delimited argument that doesn't start with \$ or % cancels macro processing.



**(./images/hmtoggle_plus0.gif)	Examples**

trace.print "Price Calc: " + price, factor1, factor2

trace.print (1) var1,var2

debug.print (1,"beta,i/o,2.0") var3,var4

trace.pause (27,"alpha"),"total="+totx



The first example demonstrates the original syntax and the fact that the new clauses are entirely optional.

The second example uses the new clause to specify a debug level of 1, which makes the TRACE.PRINT equivalent to DEBUG.PRINT—illustrating that the only difference between TRACE.xxx and DEBUG.xxx is the default debug level. It also illustrates that you can specify just the level without the tags argument. 

The third example illustrates the use of a tags list. Note that you must include the level argument if you using the tags list; 1 is the standard level for debug statements. It also illustrates the use of multiple values—i.e. a comma delimited list of values, as allowed in a normal PRINT statement.

The last example shows a variation using trace.pause, but note that since the level is set to 27, it won't be executed unless the runtime debug level is 27 or higher and one of the tags enabled. Also note that the totx in the expression list will not get an automatic label because it is already part of a string expression.

**Comments**

When the TRACE.xxx statements are executed on a server whose client is ATE, the message is forwarded to the ATE client to display. If the client is not ATE, the message is output to the standard ashlog.log.

**See Also**

•	The description of the DEBUG system variable in the [A-Shell Extensions](a-shellextensions.htm.md) table. 

•	[TRACE\_BEGIN and \_END](trace_beginand_end.htm.md)

•	[SET.LIT…DEBUG](debugsettings.htm.md) to set the runtime debug level, tags, and tracing destination.

•	[Debugging Techniques](debugging-techniques.htm.md)



**(./images/hmtoggle_plus0.gif)	History**

2025 October, A-Shell 7.0.1779:  Add macros \$D and \$I and the comma delimited option. 

2019 November, A-Shell 6.5.1671, compiler edit 921:  Optimizes the runtime code generated by trace statements of the forms:

DEBUG.PRINT <args>

TRACE.PRINT (level,tags) <args>

The optimization adds a few bytes to the RUN code for each statement, but eliminates nearly all of the overhead associated with runtime evaluation in the caes where where no DEBUG level or tags have been set, as would be typical for most production environments. Previously, the overhead, while small, was enough to become significant when such statements were embedded in code executed in tight loops. This partially undermined the advantage of being able to insert many such traces into code so that they could be activated selectively for debugging purposes.

Note while the optimization requires runtime version 6.5.1671.0+ to be effective, it will containue to run with older runtimes but without the benefit of the optimization.

2018 July, A-Shell 6.5.1639, compiler edit 861:  Expanded xxxxxx.PRINT and xxxxxx.PAUSE statements

2018 July, A-Shell 6.5.1639:  Add \$L macro