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 kill command. 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.