A-Shell Reference

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:

These offer several advantages over the plain vanilla PRINT statements:

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 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 (generated by the COMPIL /LF 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 to the list of variables, e.g.

trace.print (9, "tags") "$# $T #L", ABC_CURRENT_ROUTINE$, amount, subtotal, name$

See TRACE Statements for more details.

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 for details.

A-Shell supports many internal trace options that can be enabled and disabled via the SET TRACE 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, 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_SETTRACEXS.

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

VIEWASHLOG.LIT is a general purpose viewer for the ashlog.log files, with several options which can be particularly useful for debugging, such as:

ADB.LIT 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.