A macro is a file that contains one or more ADSM administrative commands. You can only issue macros from the administrative client in batch or interactive modes.
The name for a macro file must follow the naming conventions of the administrative client running on your operating system. See "File Naming Conventions for Redirected Output" for details.
A macro invoked from the adsm> prompt is called a high-level macro. Any macros invoked from within the high-level macro are called nested macros. You can include the MACRO command within a macro file to invoke other macros up to ten levels deep.
Creating a macro file to enter commands can be especially helpful when you want to issue commands that are used repeatedly. For example, you can create a macro file that contains a command to define a storage pool. By using variables for the keyword values in the file, you can define a storage pool without having to type all the keyword parameters.
You can also enter commands in a macro file to process related commands in a specific order. For example, you could create a macro file that contains commands to define a new schedule and to associate client nodes to that schedule. Or, you could create a macro file that contains commands to define a new policy set, validate it, and make it the active policy set for a policy domain.
In a macro that contains several commands, you can use the COMMIT and ROLLBACK commands to control command processing within the macro. See "Controlling Command Processing in a Macro" for information about using those commands.
When you write administrator commands in a macro, use the general rules stated in Chapter 2. "Entering Administrative Commands". ADSM ignores any blank lines included in your macro. However, a completely blank line terminates a command that is continued (with continuation characters).
Refer to "Using Macros to Issue Commands" for information about how to name a macro file.
Here is an example of a macro called REG.MAC that registers and grants authority to a new administrator:
REGister Admin pease mypasswd - CONtact='David Pease, x1234' GRant AUTHority pease - CLasses=Policy,STorage - DOmains=domain1,domain2 - STGpools=stgpool1,stgpool2
This example uses continuation characters in the macro file to issue the commands. For more information on continuation characters, see "Using Continuation Characters".
After you create a macro file, you can update the information it contains and use it again, or you can copy the macro file, make changes to the copy, and then run the copy.
You can add comments to your macro file to document its purpose and functions.
To write a comment, write a slash and an asterisk (/*) to indicate the beginning of the comment, write the comment, and then write an asterisk and a slash (*/) to indicate the end of the comment. You can put a comment on a line by itself, or put it on a line that contains a command or part of a command.
For example, to use a comment to identify the purpose of a macro, write the following:
/* AUTH.MAC-Register new nodes */
Or, to write a comment to explain something about a command or part of a command, write:
DOmain=domain1 /*Assign node to DOMAIN1 */
Comments cannot be nested and cannot span lines. Every line of a comment must contain the comment delimiters.
You can use substitution variables in a macro to supply values for commands when you run the macro. When you use substitution variables, you can use a macro again and again, whenever you need to perform the same task for different objects or with different parameter values.
A substitution variable consists of a percent sign (%), followed by a number that indicates the number of the substitution variable. When you run the file with the MACRO command, you must replace the numbered substitution variable with a string.
For example, to create a macro named AUTH.MAC to register new nodes, write it as follows:
/* Register new nodes */ REGister Node %1 %2 - /* userid password */ CONtact=%3 - /* 'name, phone number' */ DOMain=%4 /* policy domain */
Then, when you run the macro, you enter the values you want to pass to the server to process the command.
If your system uses the percent sign as a wildcard character, a pattern-matching expression in a macro where the percent sign is immediately followed by a numeric digit is interpreted by the administrative client as a substitution variable.
You cannot enclose a substitution variable in quotation marks. However, a value you supply as a substitution for the variable can be a quoted string.
For example, to register the node named DAVID with a password of DAVIDPW, with his name and phone number included as contact information, and assign him to the DOMAIN1 policy domain, enter:
MACRO auth.mac david davidpw "David Pease, x1234" domain1
You can enter the MACRO command in batch or interactive mode.
If the macro does not contain substitution variables, (such as the REG.MAC macro described in the "Writing Commands in a Macro File" ), to run the macro simply enter the MACRO command with the name of the macro file. For example:
MACRO reg.mac
If the macro contains substitution variables, (such as the AUTH.MAC macro described in "Using Substitution Variables in a Macro"), include the values that you want to supply after the name of the macro. Each value is delimited by a space. For example:
MACRO auth.mac pease mypasswd "david pease, x1234" domain1
If you enter fewer values than there are substitution variables in the macro, ADSM replaces the remaining variables with null strings.
If you want to omit one or more values between values, enter a null string ("") for each omitted value. For example, if you omit the contact information in the previous example, you must enter:
MACRO auth.mac pease mypasswd "" domain1
When you issue a MACRO command, the server processes all commands in the macro file in order, including commands contained in any nested macros. The server commits all commands in a macro after successfully completing processing for the highest-level macro. If an error occurs in any command in the macro or in any nested macro, the server terminates processing and rolls back any changes caused by all previous commands.
If you specify the ITEMCOMMIT option when you enter the DSMADMC command, the server commits each command in a macro individually, after successfully completing processing for each command. If an error occurs, the server continues processing and only rolls back changes caused by the failed command.
You can control precisely when commands are committed with the COMMIT command. If an error occurs while processing the commands in a macro, the server terminates processing of the macro and rolls back any uncommitted changes (commands that have been processed since the last COMMIT). Make sure your administrative client session is not running with the ITEMCOMMIT option if you want to control command processing with the COMMIT command.
| Note: | Commands that start background processes cannot be rolled back. For a list of commands that can start background processes, see "Commands Processed in the Background". |
You can test a macro before implementing it by using the ROLLBACK command.
You can enter the commands (except the COMMIT command) you want to issue in the macro, and enter ROLLBACK as the last command. Then, you can run the macro to verify that all the commands process successfully. Any changes to the database caused by the commands are rolled back by the ROLLBACK command you have included at the end. Remember to remove the ROLLBACK command before you make the macro available for actual use. Also, make sure your administrative client session is not running with the ITEMCOMMIT option if you want to control command processing with the ROLLBACK command.
If you have a series of commands that process successfully via the command line, but are unsuccessful when issued within a macro, there are probably dependencies between commands. It is possible that a command issued within a macro cannot be processed successfully until a previous command, that is issued within the same macro, is committed. Either of the following actions allow successful processing of these commands within a macro:
COMMAND A
COMMAND B
COMMIT
COMMAND C