Passing a command argument to a macro

As described in Creating and running a macro, many commands require arguments when used within a macro. You can use either a standard macro variable or a standard Client function to pass an argument to a command at the time the macro runs.

Using the &argstring variable

To use the &argstring variable to pass an argument to a command in a macro:

1. In the macro, specify&argstring where you would normally specify the command argument.

For example, note the use of &argstring in the breaksAt command in the following macro:

# Run till line that matches the user-passed string  top  clearBreaks   breaksAt &argstring  run  clearBreaks 

Note: For commands that have multiple arguments, use the numbered-argument function, &&arg(n), to distinguish the arguments. For example:

traceUntilVariableEqualsValue &&arg(1) &&arg(2) 

2. Provide the actual argument value before or as you run the macro.

This depends on how you invoke the macro:

• If you use the Run Macro option of the Macros menu, the contents of the Entity name text box  replace instances of &argstring in the commands in the macro.

• If you use the Command Line option of the Macros menu, you explicitly specify in the command line tool the replacement for &argstring.

• If you use an associated button or key, the &argstring replacement depends on whether the macro command in the mapping in the ui.xml file is specified with or without arguments:

• If the macro command has an argument (after the name of the macro), that argument replaces &argstring in the macro. For example, if this is the mapping:

<mapping command="macro stooge moe" key="f2" /> 

Pressing the F2 key invokes the stooge macro with moe as the replacement argument for instances of &argstring.

• If the macro command is specified without an argument, the contents of the Entity name text box replace &argstring.

Using the &&prompt function

The &&prompt function causes a macro to:

1. Pause, to accept a user supplied argument value for a command that is specified within the macro
2. Continue, to execute the command with the supplied value

The format of the &&prompt function is:

&&prompt(prompt) 

where prompt is either:

• A single- or double-quoted character string with 80 or fewer characters.

• A Client macro variable.

As an example, the following macro clears all breaks in the current source code, prompts for the string it will use as the argument for the breaksAt command, then executes the code from its current position until it reaches a line that contains the user-supplied string, after which it clears the break:  

# Run till first line that has the string entered at the prompt  top  clearBreaks  breaksAt &&prompt("Enter the string at which to break:") run  clearBreaks 

When the macro command that contains &&prompt executes, the Client displays a Macro prompt dialog box like the following, which shows the prompt string from the preceding example macro:

You can use the &&prompt function wherever an argument to a command may appear, as shown in the following example:

traceUntilVariableEqualsValue &&prompt('var') &&prompt("val") 

When this command executes, it produces two consecutive prompts, one for each of the command arguments.