8 DEFINING AND USING MACROS

This chapter contains the following sections:

CrossView Pro Macros
Defining Macros
Listing Macros
Redefining a Macro
Saving Macro Definitions to a File
Loading Macro Definitions from a File
Deleting Macros
Macro Parameters
Redefining Existing CrossView Pro Commands
Using the Toolbox
Opening the Toolbox
Connecting Macros to the Toolbox
Removing a Macro Connection

8.1 CrossView Pro Macros

A macro is a user-created shorthand for any sequence of CrossView Pro or C commands and expressions. Macros allow you to debug more efficient when using CrossView Pro by substituting a short string for a longer combination of words and evaluators.

You can use a macro anywhere an CrossView Pro or C expression is valid: in a breakpoint's command list, with assertions, from the keyboard, among other places. CrossView Pro also allows you to save macro definitions, so they are always available. By passing parameters to a macro, you can create powerful and flexible macros to debug your code more efficiently.

You can use macros in the Command Window, or connect them to the graphic interface in a feature called the toolbox. You can have this toolbox visible as a CrossView Pro window and use it to execute a macro by clicking a button. You control which macros have corresponding buttons, making the toolbox easy to adapt to different situations.

8.2 Defining Macros

You can create as many macros as you want:

From the Tools menu, select Macro Definitions... to open the Macro Definitions dialog box and click on the New... button.

Figure 8-1: Macro Definitions

In the Command Window, use the set command followed by the macro's invocation name and the list of commands. Note that the list of commands must be in (double) quotation marks. For example, the command:

creates a macro call st that tells CrossView Pro to change the viewing position to be the first executable line in the function main( ) and restart the program from the beginning. Each time you enter st in the Command Window, CrossView Pro substitutes the lengthier list of commands in the definition.

FUNCTION: Create a macro.

COMMAND: set name "commands"

Note that there is no rule that the macro definition must be shorter than the commands it represents. For instance, you could substitute break for the b command, to make CrossView Pro's command language more expressive:

Now instead of typing 74 b to set a breakpoint, you can also type:

Macros defined using either the command line or the graphic interface are accessible both from the Command Window and the Toolbox.

Macros may call other macros, so it is possible to use simple macros as building blocks for more complex functionality. No macro, however, can call itself, or another macro that refers to the calling macro, since this type of action results in infinite recursion.

Because of the order in which CrossView Pro parses statements, you may not use the CrossView Pro commands # or % in a macro.

8.2.1 Listing Macros

From the Tools menu, select Macro Definitions... to open the Macro Definitions dialog box. This dialog box contains a scrollable list of the macros.

To see the current definition of a macro:

Follow these steps:

Type the echo name command in the Command Window. For instance, to see the definition for the st macro:

FUNCTION: Display macro expansion.

COMMAND: echo name

8.2.2 Redefining a Macro

If you want to change the definition of a macro:

From the Tools menu, select Macro Definitions... to open the Macro Definitions dialog box. Click on the name of the macro you want to change and click on the Edit... button.

In the Command Window, use the set command again, but enter an exclamation point after the macro name. For instance, to redefine the macro st, which was defined in the example above, use the command:

Now, the st macro changes the viewing position and restarts program execution, placing a temporary breakpoint at line 56. Be sure you do not include a space before the exclamation point. Otherwise, CrossView Pro may interpret the ! as the C "not" operator.

8.2.3 Saving Macro Definitions to a File

You can save all the macros you define in a debugging session in an external file. This way, you do not lose the definitions when the program ends.

To save macros to an external file:

Follow these steps:

Type the save file command in the Command Window. This command saves your macros to the file of your choice. For instance:

FUNCTION: Save macros to a file.

COMMAND: save filename

8.2.4 Loading Macro Definitions from a File

You can load saved macros anytime you want to re-use a definition. There is no limit to the number of times you can load macros.

To load a macro file:

Follow these steps:

To reinstate your macro definitions from the Command Window, use:

You must load a program before you can read a macro definition file. Autoload will be ignored when the Execute these settings at CrossView startup check box in the Load Symbolic Debug Info dialog box is not checked.

For more information on record and playback functions, see the next chapter, Command Recording & Playback.

8.2.5 Deleting Macros

To delete a specific macro:

Follow these steps:

Type the unset command in the Command Window. For example, to remove the st macro, enter:

When you are removing a macro definition in this manner, you must place an exclamation point after the macro name to prevent CrossView Pro from expanding the name to its full macro definition. To update your macro definition files, issue a save command after using unset.

You can remove all existing macro definitions by entering the unset command by itself. CrossView Pro prompts you for confirmation before deleting the macros:

FUNCTION: Delete a macro.

COMMAND: unset name!

8.3 Macro Parameters

Macros can accept arguments. Parameters are labelled sequentially in a macro definition: $1, $2, $3, etc. Note that $0 has no meaning. When you invoke a macro with parameters, enclose the parameters with parentheses and separate them with commas.

CrossView Pro macros can accept any number of parameters, so it is possible to create very complex command shortcuts. You may use any type of parameter when defining a macro, including integers, strings, or addresses. Note, however, that you must pass the macro the correct type at invocation.

For instance, suppose you want to set a detailed breakpoint on any number of lines and a parameter is to specify each line number on which to install a breakpoint. Defining a macro named brk, type in the Macro Definitions dialog box:

or type in the Command Window:

In this case, the argument $1 represents the intended line number. To use the brk macro, type:

CrossView Pro replaces every instance of $1 with the value 72. For this example, that means a breakpoint is set at line 72.

8.4 Redefining Existing CrossView Pro Commands

Using macros, you can even redefine an existing CrossView Pro command.

For instance, you could redefine the breakpoint command b to always place a breakpoint at line 72 of your source code. To do this, enter the command:

CrossView Pro now interprets the b command as 72 b.

The exclamation point in the definition is necessary to prevent infinite recursion. It tells CrossView Pro to take the command literally and to not expand it into a macro definition. For example:

CrossView Pro interprets this command as the standard breakpoint command and places a breakpoint at line 66, despite the macro definition for b.

Be sure not to have any space between the command and the exclamation point. Otherwise CrossView Pro may interpret the ! as the C not operator.

8.5 Using the Toolbox

The CrossView Pro toolbox, shown in figure 8-2, is controlled from the View menu. Using the Tools menu, you can configure the toolbox and define the macros for it. You can resize the toolbox to the size you want.

Figure 8-2: CrossView Pro Toolbox

8.5.1 Opening the Toolbox

To open the toolbox:

From the View menu, select Toolbox.

The Toolbox is a pop-up window that remains on top of the CrossView Pro Desktop while you work in other windows.

8.5.2 Connecting Macros to the Toolbox

To configure the toolbox, select Toolbox Setup... from the Tools menu to view the Toolbox Setup dialog box, shown in figure 8-3. This dialog box displays the toolbox buttons and an alphabetized list of the current macro definitions.

To connect a macro to a toolbox button:

Follow these steps:

Note that double clicking on the macro name in the alphabetized list performs the third step automatically. The name of the new function appears on the selected button and the connection is performed.

Figure 8-3: Setting Up the Toolbox

Do not assign parameterized macros to the toolbox since there is no way to pass in parameter values.

8.5.3 Removing a Macro Connection

To delete a macro definition from the toolbox:

Follow these steps:

This deletes the macro definition from the toolbox.


Copyright © 2002 Altium BV