A-Shell Reference

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. Also see Debug Settings 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 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.

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:

 

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.

 

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