![]() |
![]() |
Tivoli Storage Manager provides for automation of common administrative tasks with server scripts that are stored in the database. The scripts can be processed directly on the server console, the web interface, or included in an administrative command schedule. Tivoli Storage Manager provides sample scripts in scripts.smp. The sample scripts have an example order of execution for scheduling administrative commands. For more information, see Using SELECT Commands in Tivoli Storage Manager Scripts. The sample scripts can be loaded from the scripts.smp file by issuing the runfile command. See Quick Start for details.
The administrator can run the script by issuing the RUN command from the web administrative interface, or scheduling the script for processing using the administrative command scheduler on the server. If one of the specified commands in the script does not process successfully, the remaining commands are not processed.
Tivoli Storage Manager scripts can include the following:
Task | Required Privilege Class |
---|---|
Define a server script | System, policy, storage, and operator |
You can define a server script line by line, create a file that contains the command lines, or copy an existing script.
The following examples use commands to define and update scripts. However, you can easily define and update scripts using the web administrative interface where you can also use local workstation cut and paste functions.
You can define a script with the DEFINE SCRIPT command. You can initially define the first line of the script with this command. For example:
define script qaixc "select node_name from nodes where platform='aix'" desc='Display AIX clients'
This example defines the script as QAIXC. When you run the script, all AIX clients are displayed.
To define additional lines, use the UPDATE SCRIPT command. For example, you want to add a QUERY SESSION command, enter:
update script qaixc "query session *"
You can specify a WAIT parameter with the DEFINE CLIENTACTION command that allows the client action to complete before processing the next step in a command script or macro. See Administrator's Reference for information
You can use the ISSUE MESSAGE command to determine where a problem is within a command in a script. See Administrator's Reference for information on how to use the ISSUE MESSAGE command.
For additional information about updating server scripts, or updating a command line, see Updating a Script.
You can define a script whose command lines are read in from another file that contains statements for the script to be defined. For example, to define a script whose command lines are read in from the file BKUP12.MAC, issue:
define script admin1 file=bkup12.mac
The script is defined as ADMIN1, and the contents of the script have been read in from the file BKUP12.MAC.
You can continue long commands across multiple command lines by specifying the continuation character (-) as the last character for a command that is continued. The following example continues an SQL statement across multiple command lines:
/*-----------------------------*/ /* Sample continuation example */ SELECT- * FROM- NODE WHERE- PLATFORM='win32'
When this command is processed, it runs the following:
select * from nodes where platform='win32'
You can include substitution variables in a script. Substitution variables are specified with a $ character followed by a number that represents the position of the parameter when the script is processed. The following example SQLSAMPLE script specifies substitution variables $1 and $2:
/*----------------------------------------------*/ /* Sample substitution example */ /* ---------------------------------------------*/ SELECT- $1 FROM- NODES WHERE- PLATFORM='$2'
When you run the script you must specify two values, one for $1 and one for $2. For example:
run sqlsample node_name aix
The command that is processed when the SQLSAMPLE script is run is:
select node_name from nodes where platform='aix'
You can use conditional logic flow statements based on return codes issued from previous command processing. These logic statements allow you to process your scripts based on the outcome of certain commands. You can use IF, EXIT, or GOTO (label) statements.
As each command is processed in a script, the return code is saved for possible evaluation before the next command is processed. The return code can be one of three severities: OK, WARNING, or ERROR. Refer to Administrator's Reference for a list of valid return codes and severity levels.
You can use the IF clause at the beginning of a command line to determine how processing of the script should proceed based on the current return code value. In the IF clause you specify a return code symbolic value or severity.
The server initially sets the return code at the beginning of the script to RC_OK. The return code is updated by each processed command. If the current return code from the processed command is equal to any of the return codes or severities in the IF clause, the remainder of the line is processed. If the current return code is not equal to one of the listed values, the line is skipped.
The following script example backs up the BACKUPPOOL storage pool only if there are no sessions currently accessing the server. The backup proceeds only if a return code of RC_NOTFOUND is received:
/* Backup storage pools if clients are not accessing the server */ select * from sessions /* There are no sessions if rc_notfound is received */ if(rc_notfound) backup stg backuppool copypool
The following script example backs up the BACKUPPOOL storage pool if a return code with a severity of warning is encountered:
/* Backup storage pools if clients are not accessing the server */ select * from sessions /* There are no sessions if rc_notfound is received */ if(warning) backup stg backuppool copypool
The EXIT statement ends script processing. The following example uses the IF clause together with RC_OK to determine if clients are accessing the server. If a RC_OK return code is received, this indicates that client sessions are accessing the server. The script proceeds with the exit statement, and the backup does not start.
/* Back up storage pools if clients are not accessing the server */ select * from sessions /* There are sessions if rc_ok is received */ if(rc_ok) exit backup stg backuppool copypool
The GOTO statement is used in conjunction with a label statement. The label statement is the target of the GOTO statement. The GOTO statement directs script processing to the line that contains the label statement to resume processing from that point. The label statement always has a colon (:) after it and may be blank after the colon.
The following example uses the GOTO statement to back up the storage pool only if there are no sessions currently accessing the server. In this example, the return code of RC_OK indicates that clients are accessing the server. The GOTO statement directs processing to the done: label which contains the EXIT statement that ends the script processing:
/* Back up storage pools if clients are not accessing the server */ select * from sessions /* There are sessions if rc_ok is received */ if(rc_ok) goto done backup stg backuppool copypool done:exit
You can update, copy, rename, query, delete, and run server scripts.
Task | Required Privilege Class |
---|---|
Update, copy, rename, query, and delete a script
Run a script | System, policy, storage, and operator |
You can update a script to change an existing command line or to add a new command line to a script.
To change an existing command line, specify the LINE= parameter.
To append a command line to an existing script issue the UPDATE SCRIPT command without the LINE= parameter. The appended command line is assigned a line number of five greater than the last command line number in the command line sequence. For example, if your script ends with line 010, the appended command line is assigned a line number of 015.
The following is an example of the QSTATUS script. The script has lines 001, 005, and 010 as follows:
001 /* This is the QSTATUS script */ 005 QUERY STATUS 010 QUERY PROCESS
To append the QUERY SESSION command at the end of the script, issue the following:
update script qstatus "query session"
The QUERY SESSION command is assigned a command line number of 015 and the updated script is as follows:
001 /* This is the QSTATUS script */ 005 QUERY STATUS 010 QUERY PROCESS 015 QUERY SESSION
Line number 010 in the QSTATUS script contains a QUERY PROCESS command. To replace the QUERY PROCESS command with the QUERY STGPOOL command, specify the LINE= parameter as follows:
update script qstatus "query stgpool" line=10
The QSTATUS script is updated to the following:
001 /* This is the QSTATUS script */ 005 QUERY STATUS 010 QUERY STGPOOL 015 QUERY SESSION
To add the SET REGISTRATION OPEN command as the new line 007 in the QSTATUS script, issue the following:
update script qstatus "set registration open" line=7
The QSTATUS script is updated to the following:
001 /* This is the QSTATUS script */ 005 QUERY STATUS 007 SET REGISTRATION OPEN 010 QUERY STGPOOL 015 QUERY SESSION
You can copy an existing script to a new script with a different name. For example, to copy the QSTATUS script to QUERY1 script, issue:
copy script qstatus query1
The QUERY1 command script now contains the same command lines as the QSTATUS command script.
You can query a script to display information about the script. You
can specify wildcard characters to display all scripts with names that match a
particular pattern. When you query a script, you can direct the output
to a file in a file system that the server can access. The various
formats you can use to query scripts are as follows:
Format | Description |
---|---|
Standard | Displays the script name and description. This is the default. |
Detailed | Displays commands in the script and their line numbers, date of last update, and update administrator for each command line in the script. |
Lines | Displays the name of the script, the line numbers of the commands, comment lines, and the commands. |
Raw | Outputs only the commands contained in the script without all other attributes. You can use this format to direct the script to a file so that it can be loaded into another server with the DEFINE script command specifying the FILE= parameter. |
The following is an example for querying a script in the standard format.
query script *
The command gives results like the following:
+--------------------------------------------------------------------------------+ |Name Description | |--------------- ------------------------------------------------------ | |QCOLS Display columns for a specified SQL table | |QSAMPLE Sample SQL Query | | | +--------------------------------------------------------------------------------+
For more information about querying a server script, refer to Administrator's Reference.
You can create additional server scripts by querying a script and specifying the FORMAT=RAW and OUTPUTFILE parameters. You can use the resulting output as input into another script without having to create a script line by line.
The following is an example of querying the SRTL2 script in the raw format, directing the output to newscript.script:
query script srtl2 format=raw outputfile=newscript.script
You can then edit the newscript.script with an editor that is available to you on your system. To create a new script using the edited output from your query, issue:
define script srtnew file=newscript.script
You can rename a script to a different name. For example, to rename the QUERY1 script to QUERY5, issue:
rename script query1 query5
The QUERY1 script is now named QUERY5.
You can delete an individual command line from a script. When you specify a line number, only the corresponding command line is deleted from the script.
For example, to delete the 007 command line from the QSTATUS script, issue:
delete script qstatus line=7
To delete an entire script, issue the DELETE SCRIPT command.
To delete the QSTATUS script, issue:
delete script qstatus
To process a script, issue the RUN command. You can run a script that contains substitution variables by specifying them along with the RUN command.
You can preview the command lines of a script without actually executing the commands by using the PREVIEW=YES parameter with the RUN command. If the script contains substitution variables, the command lines are displayed with the substituted variables. This is useful for evaluating a script before you run it.
For example, to process the QAIXC script previously defined, issue:
run qaixc
To process the following script that contains substitution variables:
/*----------------------------------------------*/ /* Sample continuation and substitution example */ /* ---------------------------------------------*/ SELECT- $1 FROM- NODES WHERE- PLATFORM='$2'
Enter:
run qaixc node_name aix
Where $1 is node_name and $2 is aix.