A-Shell Consolidated Reference

Added July 2018

Beginning with A-Shell 6.5.1639, SET.LIT 1.2(162), expanded DEBUG options are provided in order to take advantage of the expanded trace statement options:

 

The standard SET DEBUG <level> command is unchanged, except that the maximum has been increased from 9 to 2^31. Note that except for programs which explicitly map a variable named DEBUG, the runtime system will recognize DEBUG as a special system variable whose value is that specified by the SET DEBUG <level> command.

The DEBUG MIN option allows you set a minimum level, such that only those trace/debug statements specifying a level >= the DEBUG MIN level and <= the DEBUG level will be activated. The idea here is to allow different developers to set exclusive ranges so that they can easily enable their own debug traces independent of others'. Or to use different ranges for different modules (although the tags might be more suited for that).

The DEBUG TAGS option allows you to specify a list of tags (comma delimited) to be matched up with the tags in the actual trace/debug statements for the purposes of filtering which will be enabled. Tags are not case sensitive. If the list starts with "+", then individual traces will be enabled if they meet the debug level criteria OR they contain a matching tag. Otherwise statements to be enabled must match both criteria, i.e. satisfy the level AND match one of the tags.  Note that setting the DEBUG TAGS list to "" is equivalent to a wildcard matching all tags. But within the trace/debug statements themselves, and empty tag list matches only an empty DEBUG TAGS list.

To select statements by level without regard to tags, set the DEBUG TAGS to "". To select statements by tags without regard to level, specify a DEBUG TAGS list starting with "+". (To exclude traces that don't contain matching tags, use the DEBUG and/or DEBUG MIN levels to make sure that they won't match up with any of your traces. For example, if all of your trace statements are of the form DEBUG.xxx, instead of TRACE.xxx, or all of them explicitly specify a non-zero level, then just use SET NODEBUG to make sure that none are selected on the basis of the debug level. Alternatively, set the DEBUG MIN level higher than the DEBUG level.)

Note that all TRACE.xxx and DEBUG.xxx statements automatically have a special tag associated with them that matches the current program name, so to select only traces for that program, use the technique just described with SET DEBUG TAGS +program.

The DEBUG OUTPUT option controls where the trace/debug output messages go. The options for <dest> are:

 

See Also

History

2023 September, A-Shell 6.5.1744, SET.LIT(1.2) 168:  Add PREFIX option. See extended History note below.

2018 July, A-Shell 6.5.1639:  Expanded options added to AShell.

 

 

Tracing enhancement: SET.LIT 1.2(168) now supports a mechanism for globally adding tracing prefix codes:

SET DEBUG PREFIX prefix-string

where prefix-string is a string containing one or more prefix codes ($#, $P, $T, $L) to be added to all TRACE.PRINT statements. This is useful in situations where already have a large number of TRACE.PRINT statements in your code and then realize that it would be a lot more useful if they were numbered, or contained timestamps, or listed the program and location. The prefix codes specified in the SET DEBUG PREFIX statement are merged with any specified explicitly in TRACE.PRINT statements, eliminating duplicates.

For example, the SET command

SET DEBUG PREFIX $# $P

will at run time effectively convert the following

TRACE.PRINT (99,"foo") "$# $T" var1, var2

to

TRACE.PRINT (99,"foo") "$# $P $T" var1, var2

History