Creating and running a macro

A Debugger macro is a workstation text file that contains a list of Client commands to execute (as shown in the A macro example subsection). This section describes how to create and run a macro.

You run a macro from the Macros menu, from a Client button or hot key to which you have assigned a macro, or from the command line. You can also run a macro automatically:

If the macro name matches that of an included procedure (and the macro autorun preference has been selected).
At Client startup, if the macro is specified on the startUpMacro="macroname" attribute of the <mappings> tag in the UI customization file (ui.xml/uiMore.xml).

Macro definition

To define a new macro:

1. Start a text file by doing either of these:

From the Client's File menu, select New Blank Macro.

The "Select name for a new macro" Windows dialog box opens, from which you select where to locate and what to name the macro file.

Macro files must have a .macro file extension, and the file name must not contain embedded blanks.

When you click the Save button, the macro file opens in Notepad.

Alternatively, create a new file in a Windows text editor like Notepad.

When you later name and save this file after defining its contents, you must specify a .macro file extension and make sure the file name contains no embedded blanks.

Note: If you decide to store the file in a location other than the Client installation folder, see Changing the location of Client work files.

2. In the text file, specify the Debugger commands you want to be run consecutively.

These are the formatting guidelines:

Specify one command (case does not matter) per line; leading spaces and blank lines are ignored; line can be indefinitely long.
Any line that begins with a number sign (#) is treated as a comment.
Several commands require arguments; specify arguments or argument variables after the command keyword separated by at least one blank. For example:

addWatch %i searchFromTop image foo runUntil daemonnest

Separate multiple command arguments by one or more blanks. For example:

traceUntilVariableEqualsValue %i 3

For a macro to run another macro, specify either of the following:

include macroName macro macroName

Specifying the extension .macro after the macro name is optional. The following commands are equivalent:

include foo.macro

include foo

3. Save and exit the macro file.

You can easily access this file for editing by selecting the Edit Macro option from the Macros menu.

4. Consider opening the macro console (from the Macros menu) to display information about the macros you run.

The console reports the starting and completing of the macro execution, as well as any error messages.

5. Invoke the macro.

Use any of the following ways to run a macro:

From the Macros menu, select the Run Macro option.
From the Macros menu, select the Command Line option.
Use a button or hot key combination to which you have mapped the macro.
Specify the macro name as the value of the startUpMacro attribute in the Client's ui.xml file, or as the value of the startup attribute in the Client's debuggerConfig.xml file.

The title bar of the main Client window indicates that the macro is executing:

. . . macro running

Potential errors include: an invalid macro command, trying to invoke a macro that does not exist, and violating the context and recursion restrictions.

If you want to stop a macro at any time it is running or in a not-completed state awaiting further input, select the Kill Running Macro option from the Macros menu.

Note: A macro runs until it has exhausted all its commands or encounters a killcommand. If a request completes before the macro is finished, the remaining commands in the macro apply to the next request in the session. If you want to prevent these commands from being applied to the next request, use the Kill Running Macro option or the noSpan command.

A macro example

The following sample macro prepares a particular program (shown below the macro) for further debugging:

# Remove any existing breakpoints or watches
clearWatch
clearBreaks

# Set breakpoint on the first line we
# want to examine
top
breaksAt For 1 record

# watch some variables we are interested in
addWatch %i
addWatch %what

# Run to the breakpoint we set
run

The sample macro above was designed for a program like this:

begin
   %i is float
   %what is string len 30
   *BREAK
   %i = 1
   * this should not be recognized as a *break
   for 1 record
      *breaks
      %i = %i + 1
      %what = $sirtime
      change testfield to %what
   end for
   *break
   %i = %i + 1
   assert %i = 3
   trace 'hello ....'
   *break
   audit 'Hey moe...'
   print $sirtime
   print %i
end

Macro usage restrictions

These are the context and calling restrictions you must observe when using macros:

Context restrictions

Some of the commands that may appear in a macro are valid only when you are interactively running a program under the Debugger. If a macro attempts to execute one of these commands when no program code is ready or remains to execute, the macro is terminated, and the following message is displayed in the Client's Status bar:

Invalid context for: Offending command

The following types of commands are allowed only when executing a program:

All run commands
All cancel commands
All step commands
All watch commands
All breakpoint commands
All trace commands

Similarly, the following commands are allowed only after a program fails to compile. If these commands are issued when there is no compilation error, the Client issues the "Invalid context" message described above:

nextCompileError
previousCompileError

Recursion restriction

Macros may not be recursively called, either directly or indirectly. These sequences are not allowed:

"Macro Alpha calls macro Alpha" (direct recursion)
"Macro Alpha calls macro Beta which calls macro Alpha" (indirect recursion)

In either case, when a recursive call is detected, the macro is terminated and a message is displayed in the Status bar.