TSM supports macros on the administrative client. A macro is a file that contains one or more administrative client commands. You can only run a macro from the administrative client in batch or interactive modes. Macros are stored as a file on the administrative client. Macros are not distributed across servers and cannot be scheduled on the server.
Macros can include the following:
For more information on administrative commands, see Writing Commands in a Macro.
For more information on comments, see Writing Comments in a Macro.
For more information on continuation characters, see Using Continuation Characters.
For more information on variables, see Using Substitution Variables in a Macro.
The name for a macro must follow the naming conventions of the administrative client running on your operating system. For more information about file naming conventions, refer to the Administrator's Reference.
In macros that contain several commands, use the COMMIT and ROLLBACK commands to control command processing within the macro. For more information about using these commands, see Controlling Command Processing in a Macro.
You can include the MACRO command within a macro file to invoke other macros up to ten levels deep. A macro invoked from the TSM administrative client command prompt is called a high-level macro. Any macros invoked from within the high-level macro are called nested macros.
Refer to the Administrator's Reference for more information on how commands are entered and the general rules for entering administrative commands. The administrative client ignores any blank lines included in your macro. However, a completely blank line terminates a command that is continued (with a continuation character).
The following 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. 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 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 continuation characters in a macro file. Continuation characters are useful when you want to execute a command that is longer than your screen or window width.
Attention: Without continuation characters, you can enter up to 256 characters. With continuation characters, you can enter up to 1500 characters. In the MACRO command, these maximums are after any substitution variables have been applied (see Using Substitution Variables in a Macro).
To use a continuation character, enter a dash or a back slash at the end of the line that you want to continue. With continuation characters, you can do the following:
register admin pease mypasswd - contact="david, ext1234"
stgpools=stg1,stg2,stg3,- stg4,stg5,stg6
contact="david pease, bldg. 100, room 2b, san jose,"- "ext. 1234, alternate contact-norm pass,ext 2345"
TSM concatenates the two strings with no intervening blanks. You must use only this method to continue a quoted string of values across more than one line.
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 specify values for the variables.
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.
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
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.
Use the MACRO command when you want to run a macro. 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), run the macro by entering 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, the administrative client 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 script or 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.
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/