9. Debugging Macros

 

Even when writing a very simple macro, never expect it to run flawlessly on the first try. Once the first version of the macro is written, the fun part of testing and debugging starts...

Up to the Release 6, no special debugging tools were available, except for switch 15. This switch, if set to ON, will cause all macro commands to be displayed on the screen while they are being executed. So, with a bit of experience and patience, switch 15 allows a macro writer to locate about any type of problem. But the really frustrating part of this way of macro debugging is that, as soon as an error occurs, the macro processing terminates immediately. This means that the macro has to be started over and over again, until all errors are found and eliminated.

With Release 7, a macro debugging tool, called single step tracing mode, has been incorporated into the macro language. This new feature offers the following possibilities:

• Execute macros in a step-by-step mode, prompting the user explicitly before each macro command is executed.
• Allow inspection of all registers and change their values if needed.
• List the contents of the macro.
• Inspect current position at all macro call level.
• Take corrective ad-hoc measures, such as skipping, inserting or replacing lines.
• Allows error recovery by falling back to single stepping mode in case of error or interruption.

The single stepping mode is activated by the setting of bit 3 of the output control register o. Once activated, it will take effect at the level of each macro line which is echoed on the dialog output with ``<....''. Which lines exactly are echoed this way is controlled by the setting of switch 15, and bits 1 and 2 of the o register.

Each macro line that is subject to single step tracing (i.e. which is displayed on the dialog in the ``<....'' format) will be displayed as usual, followed by the macro corresponding line number surrounded by tilde characters. Line and character position is listed for a macro command which is part of a compound command. The user is now expected to enter a carriage return to indicate that he is now ready to process this line.

The following example, which was taken from a macro that sets the module parameters of a graphic module, illustrates the single stepping mode:

    Enter: Width,height of nodes without node number
           (  4.00,  4.00)= < 4.0,4.0 ~L15~                         <- CR
    Enter: Width,height of nodes with node numbers    
           ( 32.00, 12.00)= < 32.0,12.0 ~L16:4~                     <- CR
    Enter: Offset to the right for links (  1.80)= < 3.0 ~L16:15~   <- CR

At each ~ prompt of the single step mode, the user has the possibility to enter either a carriage return or one of the following debugging commands:

command: action:

* Display the current values all integer registers.

t* Display the current values all text registers.

r* Display the values all non-zero general purpose floating point registers.

g* Display the current values all non-zero elements of the get()/put() stack, i.e. the gN registers.

reg Display current value of the given register reg.

reg=value Set register reg to the specified value.

:c Continue macro - leave single stepping mode. Bit 3 of the o register is reset and bit 4 (fall-back) is set, so that the single step mode is reactivated again in case of error or interrupt.

:l List current context in the macro (from 3 lines before to 3 lines after the current line).

:lN List N lines of the macro starting with the current line.

:l-N List N lines of the macro ending with the current line.

:p Display macro position at all macro call levels.

:rtext Replace the current line by text before executing it.

:s Skip the current line (do not execute it) and proceed to the next line. (Not valid in compound commands.)

:itext Insert and execute the line defined by text before executing the current line. (Not valid in compound commands.)

:x Exit macro processing.

? Display the list of available debugging commands.

Any text that follows a debugging command is subject to the usual macro substitution rules, i.e. %...% sequences will be substituted as if they would appear in the macro itself.

As indicated above, bit 4 of the output control register o activates the fall-back mode. In this mode of operation, the macro executes normally until an error condition or a user interrupt is detected. By default these events would terminate the macro processing immediately with the messages >ERROR...> or >INTERRUPT>. In fall-back mode the macro enters single stepping mode, so that the problem can immediately be analyzed and, if possible, corrected.