Tivoli Storage Manager for Windows Administrator's Guide


Tivoli Storage Manager Server Scripts

TSM 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. TSM provides sample scripts in scripts.smp. 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.

TSM scripts can include the following:

Defining a Server Script


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 *"

For additional information about updating server scripts, or updating a command line, see Updating a Script.

Defining a Server Script Using Contents of Another File

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.

Note:The file must reside on the server, and is read by the server.

Using Continuation Characters for Long Commands

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'

Using Substitution Variables

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'

Using Logic Flow Statements in a Script

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.

Specifying the IF Clause

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

Specifying the EXIT Statement

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 is not started.

/* 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

Specifying the GOTO Statement

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

Managing Server Scripts

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

Updating a Script

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.

Appending a New Command

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

Replacing an Existing Command

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

Adding a New Command and Line Number

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

Copying a Server Script

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.

Querying a Server 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 have the option of directing the output to a file in a file system that the server is able to 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.

Querying a Server Script to Create Another Server Script

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

Renaming a Server 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.

Deleting a Command from a Server Script

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

Deleting a Server Script

To delete an entire script, issue the DELETE SCRIPT command.

To delete the QSTATUS script, issue:

delete script qstatus

Running a Server Script

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.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]