Working with Objecteering macros

Overview

A macro is a series of Objecteering commands that can be grouped together within one command, in order to automate repetitive modeling operations.

Objecteering macros are written in our Java-like J language, which can be edited either in Objecteering itself or using an external text editor, such as Word, Wordpad or Notepad.

With Objecteering, you can:

· execute Objecteering macros, provided as standard with the Objecteering tool

· create your own macros

· modify macros

· delete macros

Macros are developed and implemented using the Macros MDAC. To use the Macros MDAC, simply run the "Deploy an MDAC" command from the "Tools" menu and select the Macros MDAC for deployment (for more information on deploying MDACs, please see "Working with MDACs").

Parameterizing the Objecteering Macros MDAC

The Macros MDAC can be configured in the "Modifying configuration" window, accessed through the "Tools/MDAC options" command or by clicking on the icon in the toolbar.

The Macros MDAC provides one parameter set containing two parameters (as shown below).

Macros parameters

Key:

· "Macros directory": This field indicates where standard UML macros, as well as macros created by the user, are stored. By default, this is set to $OBJING_PATH/macros. To change this directory, click on the icon to open a file browser, and select the directory of your choice.

· "Command for invoking external editor": Macros can be edited in Objecteering itself, or using an external tool such as Word, Wordpad or Notepad. To select another tool, click on the icon to open a file browser, and make your selection. Where this parameter has been defined, the tool specified is automatically used to open macro file, and takes precedence over the optional Windows jmf file association.

Note: Objecteering macro files take the .jmf suffix, meaning "J macro file".

Macro commands

When the Macros MDAC has been deployed in your project, four macro operations can be carried out:

· executing a macro

· creating a macro

· modifying a macro

· deleting a macro

To access macro commands, the user can either activate the "Macros" context menu, available by right-clicking on an element, or click on the "Macro commands" icon situated in the toolbar.

The "Macro commands" window

The "Macro commands" window interface changes according to your Objecteering installation mode.

The macros contained in "Local" are those which can be accessed from the current workstation, whilst those contained in "Server" are the macros which can be run from the server. The "Import all from server" button (heavyweight or lightweight client mode only) is used to import all macros from the server onto the current workstation.

In "Local", macros can be executed, created, modified or deleted. In "Server", macros can only be executed.

Executing macros

Objecteering comes with a number of standard macros, allowing you to:

· sort model elements by name

· sort model elements by visibility

· transform comment notes into description notes

To run an existing macro, you can either run it from the context menu or by clicking on the "Macro commands" icon. The screenshot below shows an existing macro being run from the context menu.

Running the "sortbyname" macro

Steps:

1. Select a package in the explorer by right-clicking.

2. Select the "Macros/Execute..." commands from the context menu which then appears. The "Macros" window then appears.

3. Select the "sortbyname" macro. The macro is then run on the selected element and its contents.

4. Confirm by clicking on "OK".

The package's classes are now displayed in alphabetical order.

Creating macros

To create your own macros, you can either create them from the context menu or by clicking on the "Macro commands" icon.

Creating the "Macro1" macro

Steps:

1. Select a package in the explorer.

2. Click on the "Macro commands" icon in the toolbar.

3. Click on "Local" and select the "Create" command in the combobox. The "Macros" window then appears.

4. Enter a name for your macro. Macro file names must be in lower case and must not contain blanks.

5. Enter the necessary J code.

6. Confirm by clicking on "OK".

Note: If you prefer to enter your J code using an external text editor (which has been previously specified at module parameter configuration level), simply click on the "Run external editor" button. This opens the text editor specified at module parameter configuration level (see the above screenshot).

The following guidelines should be respected when creating your own macros:

· Macro files should have a header in the following form:

* <file name>

* Version: <Macro version>

* Date: <Last modified>

* Valid for: <Metaclass on which the macro can be run>.

* <Description of the macro>

· Macro file J code should be clearly annotated, in order to facilitate comprehension of the macro.

· Code lines should not be longer than 80 characters. Where this is the case, lines are split according to Java coding conventions.

· The "return" and "exit" instructions must not be used.

· The macro must check those metaclasses on which it can be executed, so as not to produce J errors. Where a metaclass is not valid, the following error message occurs: "Error: this macro is not available on <metaclass> metaclass".

Modifying macros

To modify existing macros, you can either modify them through the "Macros/Modify..." context menu command, or through the "Macro commands" icon.

Editing the "sortbyvisibility" macro

Steps:

1. Select a package in the explorer by right-clicking.

2. Select the "Macros/Modify..." commands from the context menu which then appears. The "Macros" window then appears.

3. Select the "sortbyvisibility" macro. If you want to open this macro file using an external editor, check the "External Edition..." tickbox. The file will then be opened using the text editor specified at module parameter configuration level.

4. Make the desired modifications to the J code.

5. Confirm by clicking on the "OK" button.

Deleting macros

To modify existing macros, you can either modify them through the "Macros/Delete..." context menu command, or through the "Macro commands" icon.

Deleting a macro

Steps:

1. Select a package in the explorer.

2. Click on the "Macro commands" icon.

3. Select "Delete" in the combobox.

4. Click on "Macro1".

5. Confirm by clicking on the "OK" button.

6. A confirmation box will then appear, asking you to confirm deletion of the macro. Click on the "OK" button to confirm. The macro will then be deleted.