# Debugging Techniques

> [HTML Version](debugging-techniques.htm)

_Written August 2025_

This section provides a summary / overview of several of the various tools, techniques and methods available for debugging ASB code. 



**(./images/hmtoggle_plus0.gif)	Print Statements**

The oldest and most generic / primitive approach to debugging code is to insert PRINT statements to display variables at specific points in the logic. This is simple but unsatisfactory for several reasons, including:

•	They may interfere with the rest of the display—i.e., making it harder to see what the program is doing.

•	They might appear and disappear too fast to be seen, depending on what else is happening. You may use [STOP](stopstmt.htm.md) or some form of input to force a pause.

•	They aren’t generally visible in the AUI environment, because PRINT statements appear in the main (text) window which is generally covered up by any AUI windows.

•	It requires repeated editing and recompiling—and then you need to remove them all for the release.



**(./images/hmtoggle_plus0.gif)	Print Trace Statements**

These offer several advantages over the plain vanilla PRINT statements:

•	They can be activated and deactivated, based on keywords and/or numeric levels, without re-compilation.

•	The output can be directed to a variety of targets without interfering with the main display and therefore allowing you to study all the debug messages at leisure.

•	The syntax options allow for additional meta information to be easily included in the traces, making them both faster/easier to enter and providing more detailed and standardized output.

For example, the following statement...

Trace.print (9, “foo,bar,ledger”) “\$# \$T \$L Look Mom\!”, amount, subtotal, name\$

... would output to the target location something like the following, assuming that the session DEBUG level was 9 or above, and/or that one of the tag keys “foo”, “bar” or “ledger” has been declared via a [SET DEBUG](debugsettings.htm.md) command:

1 15:19:35 00044b Look Mom\!  amount=\[123\], subtotal=\[5999.3\], name\$=”Homer”

While the statement may look complicated, the real beauty is that you can leave them in the code and just enable them when the need arises. And as a practical matter, you're likely to create a text shortcut or macro containing the common elements...

trace.print (9, "tags") "\$# \$T #L", 

... and copy/insert it in many places, potentially changing just the "tags" and appending a list of variables.

Note that while the \$L (location) macro does indicate exactly where the trace appeared (useful when you have a lot of similar looking traces to read through), it requires cross-referencing the hex numeric location with an [LSX file](lsxfilescompil.htm.md) (generated by the [COMPIL /LF](lsxfilescompil.htm.md) switch). A less precise but much more readable alternative, particularly for traces inside of functions or small source modules would be to add one of the [Auto-Defined Symbols](auto-definedsymbols.htm.md) to the list of variables, e.g.

trace.print (9, "tags") "\$# \$T #L", ABC\_CURRENT\_ROUTINE\$, amount, subtotal, name\$

See [TRACE Statements](trace_statements.htm.md) for more details.



**(./images/hmtoggle_plus0.gif)	Trace PRAGMAs**

These add an additional layer of flexibility on the Trace.Print statements by allowing you to tell the compiler to auto-generate Trace.Print statements for all or selected variables within a block of code.

See [TRACE-BEGIN and TRACE-END](trace_beginand_end.htm.md) for details.



**(./images/hmtoggle_plus0.gif)	SET TRACE Options**

A-Shell supports many internal trace options that can be enabled and disabled via the [SET TRACE](trace_options.htm.md) command which can be of tremendous help in debugging code. Although these traces cannot be as tightly focused on your specific concerns as some of the techniques listed above, the big advantage is that they involve no programming.

For programs involving a lot of function and procedure calls, one particularly useful option is [FUNCS](trace_option_funcs.htm.md), which traces the values being passed into and returned from all functions and procedures.

Note that although some of the TRACE options may be quite verbose, you can further fine tune the process by enabling/disabling them within your program using [MX\_SETTRACE](mx_get_set_trace.htm.md)[XS](keyword-types.htm.md).



**(./images/hmtoggle_plus0.gif)	Log Files**

Although Trace.Print statements can output to log files as an option, there are other ways to generate log files with debug information:

•	[OPEN](opensequential.htm.md)[,](opensequential.htm.md) [PRINT](printstatement.htm.md) and [CLOSE](genericfiles.htm.md) statements. The main problem here is that you cannot easily enable/disable the option without adding custom logic.

•	[MX\_ASHLOG](mx_ashlog.htm.md)[XS](keyword-types.htm.md) to output messages to the main ashlog.log file. This is probably not an appropriate method for general debugging since you don’t want to unnecessarily clutter up the main log file. It might however be very good for errors and exceptions, since you get the benefits of context, log rollover, and a handy viewer utility (VIEWASHLOG, discussed below).

•	Functions from the SOSLIB, such as those in [SYSLOG.BSI in SOSLIB:\[907,12\]](https://bitbucket.org/microsabio/soslib/src/master/907012/syslog.bsi), can help you simplify and standardize your own custom log files.

•	Although this is more targeted at exception reporting than debugging per se, the SOSLIB routine [AXFLOG.SBX in SOSLIB:\[907,60\]](https://bitbucket.org/microsabio/soslib/src/master/907060/axflog.bp) provides a flexible framework for organizing and reporting a wide variety of events, including perhaps debug messages. Also see [Event Tracing](eventtracing.htm.md).



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

[VIEWASHLOG.LIT](viewashlog_lit.htm.md) is a general purpose viewer for the ashlog.log files, with several options which can be particularly useful for debugging, such as:

•	The ability to filter on one program or pid or user

•	In conjunction with compiler-generated symbol files, the ability to translate locations recorded by SET TRACE FUNCS into actual source labels, functions and procedure names.



**(./images/hmtoggle_plus0.gif)	A-Shell Debugger ADB**

[ADB.LIT](adb_lit.htm.md) is probably the most powerful and complex of the debugging tools and techniques currently available for A-Shell. It allows real-time / interactive debugging of a program running in a separate process, with the ability to set breakpoints, single step, examine individual variables, stack trace, etc.