A-Shell Reference

Updated October 2025; see History

TRACE.OPEN expr1{,expr2,...,exprN}

TRACE.PRINT 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 tags argument provides a more flexible way to activate specific TRACE statements at run time, aside from the DEBUG level, both of which 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.

Examples

 

trace.print "Hello world!"

trace.print (5), var1,var2

trace.pause (1,"beta,i/o,2.0") ABC_CURRENT_ROUTINE$, var3,var4

trace.print (27,"alpha") "$# $T $L", var5, var6, var7

 

The first example illustrates the simplest case, outputting just the message "Hello world!"

The second example illustrates the use of the level parameter to set the minimum DEBUG level to activate the trace to 5.  The output would look something like:  "var1=[77], var2=[foo]"

The third example adds tags (beta, i/o and 2.0), any of which can be specified by the SET DEBUG TAGS command to activate the trace, either dependent on or independent of the specified DEBUG level (5).  It also illustrates use of a defined symbol in place of a literal string expression or variable. (ABC_CURRENT_ROUTINE$ equates to the name of the current function.)  And, because it is trace.pause, it prompts the user to double-click to resume program operation (requires that the trace output be set to the default message window).

The last example adds macros to display the message number, time, and program location counter along with the specified variables.

 

===================================================

===================================================

 

 

Examples

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

History

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