Integrating with Tivoli Storage Manager

How HCL Workload Automation integrates with Tivoli® Storage Manager.

This chapter describes how HCL Workload Automation integrates with Tivoli Storage Manager version 5.4 and later, an enterprise-wide storage management application that provides automated storage management services to workstations, personal computers, and file servers from a variety of vendors, with a variety of operating systems.

Integration with Tivoli Storage Manager is supported only on UNIX and Linux systems.

Tivoli Storage Manager administrators perform several types of operations regularly each day using a built-in scheduling facility, which provides a simple mechanism to automate routine tasks. This scheduling facility, however, does not provide the ability to assign dependencies among scheduled tasks, to assign limits or priorities, or to define workstation classes.

Using the extended agent, you can integrate Tivoli Storage Manager with HCL Workload Automation and assign dependencies among Tivoli Storage Manager scheduled tasks or assign limits or priorities.

You can schedule the following Tivoli Storage Manager tasks using HCL Workload Automation:
  • Server administrative tasks
    • Database backup
    • Volume history backup
    • Device configuration backup
    • Delete volume history
    • Inventory expiration
    • All the other administrative tasks. For details see the IBM® Tivoli® Storage Manager Administrator's Reference.
    These tasks are run in the Tivoli® Storage Manager Command Line Administrative Interface, which must be active.
  • Client backup task
This task is run in the Tivoli® Storage Manager Command Line Backup/Archive Client Interface, which must be active.

To integrate Tivoli Storage Manager with HCL Workload Automation you must set up your environment and define appropriate jobs, as described in the following sections.

Setting up the environment
To integrate Tivoli Storage Manager with HCL Workload Automation, a specific extended agent, the tsmxagent, is needed to run Tivoli® Storage Manager commands. The tsmxagent runs only on UNIX and Linux systems.

When you install the HCL Workload Automation, the tsmxagent.sh script, representing the Tivoli Storage Manager access method, and its method options file, tsmxagent.opts, are copied to the TWS_HOME/methods directory.

To schedule a job in HCL Workload Automation to run Tivoli Storage Manager commands for administrative and client backup purposes, perform the following steps:
  1. Type the user ID of the Tivoli® Storage Manager administrator that accesses the Tivoli Storage Manager server in the tsmAdmin variable of the tsmxagent.opts file. The default value is admin.
  2. Set the password of the Tivoli® Storage Manager administrator, defined in the previous step, in the TSMPASS parameter defined using the HCL Workload Automation parms utility.
  3. Define an extended agent workstation that uses the tsmxagent access method. This logical workstation definition must be hosted by a HCL Workload Automation physical workstation, either a master domain manager, a domain manager, or a fault-tolerant agent workstation. An example is the following:
    CPUNAME TSMXAGENT 
    OS UNIX 
    NODE dontcare 
    TCPADDR 31111 
    FOR MAESTRO    
     HOST TWSFTA    
     ACCESS "tsmxagent"    
     TYPE X-AGENT 
    END
    In this case, TSMXAGENT is the name of the extended agent workstation, dontcare is the node name, 31111 is the TCP address, TWSFTA is the host, and tsmxagent is the name of the access method referred to the tsmxagent.sh script. The tsmxagent.sh must be present in all the agents TWS_HOME/methods directory. The NODE and TCPADDR definitions are ignored.
Defining jobs for Tivoli® Storage Manager tasks
You can schedule the following Tivoli Storage Manager tasks using HCL Workload Automation. The Tivoli® Storage Manager tasks must be specified in the task string for the tsmxagent job.
Server administrative tasks
  • Database backup (BACKUP DB).
  • Volume history backup (BACKUP VOLHISTORY).
  • Device configuration backup (BACKUP DEVCONFIG).
  • Delete volume history (DELETE VOLHISTORY).
  • Inventory expiration (EXPIRE INVENTORY).
  • All the other administrative tasks. For details see the IBM® Tivoli® Storage Manager Administrator's Reference.
You can use Tivoli® Storage Manager commands syntax for every Server administrative task. For the tasks listed above you can also use the alternative HCL Workload Automation key word listed in the following table:
Table 1. Mapping table between Tivoli Storage Manager and HCL Workload Automation administrative tasks
Tivoli Storage Manager command HCL Workload Automation keyword
backup db DBBACKUP
backup volhistory VHBACKUP
backup devconfig DCBACKUP
delete volhistory DELVOLHIST
expire inventory EXPIREINV
any Tivoli® Storage Manager admin command
Client backup task
  • Client backup task:
    • Client backup (DEFINE SCHEDULE, DEFINE ASSOCIATION, and DEFINE CLIENTACTION).
Client backup task can be performed using different commands. The following command uses positional syntax:
  • CLIENT DOMAIN SCHEDULE CLIENT [optional_parms]
    where:
    Table 2. Positional client backup task syntax table
    HCL Workload Automation option Description
    DOMAIN Specifies the name of the Tivoli® Storage Manager policy domain to which this schedule belongs.
    SCHEDULE Specifies the name of the schedule that you want to associate with one or more clients.
    CLIENTS Specifies the name of a server-prompted Tivoli® Storage Manager client ready for scheduling a backup.
    OPTION ARGS Specifies the optional parameters supported by the Tivoli® Storage Manager.
    The syntax of the CLIENTACT and CLIENTSCHED commands does not use positional syntax, but uses parameters to specify Tivoli® Storage Manager options values, as follows:
  • CLIENTACT -action <action name> [-domain <policy domain> ] 
    [-node <TSM node name>] [-script <value>] [--  <TSM options>]
  • CLIENTSCHED -action <action name> -domain <policy domain>  
    -node <TSM node name> [-polling <value>] 
    [-script <value>] [-timeout <value>] 
    [-schedname  <TSM schedule name> | -schedprefix 
              <TSM prefix schedule name>] 
    [-nodel] [--  <TSM options>]
where:
Table 3. Parameter client backup task syntax table
Parameter Description Default value
<-action action name> Tivoli® Storage Manager Define Schedule action (see IBM® Tivoli® Storage Manager Administrator's Reference).
<-domain policy domain> Tivoli® Storage Manager Policy Domain.
<-node TSM node name> Name of the Tivoli® Storage Manager client on which to run the script.
<-polling value> Time to wait before the next status poll. 60 seconds
<-script value> The script to run when the -action command is specified. Use '\\' instead of '\'.
Note: Due to script name parsing, avoid using " -" in the script path\name.
<-timeout< value> Number of polls to complete before timing out. 0 = Poll Forever
<-schedname tm tmtype="reg" trademark="Tivoli">Tivoli/tm> Storage Manager <schedule name> The name of the Tivoli® Storage Manager schedule. If the length of the name is more than MAX_TSM_SUPPORTED_LENGTH, the access method will truncate the name. <TWSJOB_JOB_ID>
<–schedprefix Tivoli® Storage Manager prefix schedule name> The prefix of the Tivoli® Storage Manager schedule. The schedule name is: TSM prefix name>_JOB_ID. If the length of the prefix is more than: MAX_TSM_SUPPORTED_LENGTH – LENGTH_JOB_ID + 1 the access method will truncate the prefix. <TWSJOB_JOB_ID>
-nodel Specifies that, at job completion, the Tivoli® Storage Manager schedule is not deleted. By default the schedule is deleted
-- <TSM options> Any Tivoli®Storage Manager options you want to add to theTivoli®Storage Manager Define Schedule command to be run.Note: When multiple values are required for a Tivoli® Storage Manager option, enclose the values in escaped double quotes, for example \"values>\".This is true if you are not specifying client options (https://www.ibm.com/docs/en/tsm/7.1.0?topic=options-client-reference). In case any of the options above are used, then the correct sintax is: options=<TSM options>
The differences between the types of the client task commands are the following:
  • The CLIENT and CLIENTSCHED options define a Tivoli® Storage Manager schedule and associate it to the specified NODE. The Tivoli® Storage Manager commands are run asynchronously. Use the CLIENTSCHED option when you want to trace the Tivoli® Storage Manager scheduled commands which have run, because it is possible to define a unique schedule name.
  • The CLIENTACT option allows you to launch client commands synchronously, without explicitly defining a Tivoli® Storage Manager schedule. Use it when Tivoli® Storage Manager is configured to automatically purge asynchronous schedules at midnight, so that you do not have to purge them manually. Tivoli® Storage Manager is unable to return status information for jobs after midnight if they start before midnight.
The names of the Tivoli® Storage Manager schedules must be unique to run multiple HCL Workload Automation instances of the same job at the same time. To manage the concurrency and traceability, the tsmxagent access method has been changed. Using the CLIENTSCHED command, it is possible to define a unique name for the Tivoli® Storage Manager schedule. There are two possibilities:
  • Choose no name and allow the access method to automatically generate the Tivoli® Storage Manager schedule name. This choice creates a schedule name which has the following format: “TWSJOB”_JOB_ID>, where JOB_ID is the unique identifier assigned by HCL Workload Automation to the job.
  • Choose a prefix to concatenate to the JOB_ID> to create the Tivoli® Storage Manager schedule name. This choice creates a schedule name which has the following format: schedule_prefix>_JOB_ID>, where the schedule_prefix> is defined by passing the new parameter –schedprefix to the CLIENTSCHED command and JOB_ID> is the unique identifier assigned by HCL Workload Automation to the job.

It is also possible to choose a non-unique schedule name. In this case, concurrency and traceability are not supported. This choice is enabled passing the parameter -schedname to the CLIENTSCHED command. The Tivoli® Storage Manager schedule is defined with the name <schedule_name>.

Using the CLIENT option, concurrency and traceability are not supported because, running the same HCL Workload Automation job on the x-agent, you have the following results:
  • Tivoli® Storage Manager schedules created with the same name are not allowed and so the HCL Workload Automation job ends unsuccessfully.
  • After the unsuccessful completion of one of the HCL Workload Automation job which must run concurrently, the Tivoli® Storage Manager schedule is deleted and so all the other jobs end unsuccessfully.
  • The entries produced in the log files have the same name and you cannot distinguish between them.
To allow the rerun of a HCL Workload Automation job that uses the Tivoli® Storage Manager extended agent, the Tivoli® Storage Manager schedule must be deleted after its completion, otherwise the rerun of the HCL Workload Automation job fails because Tivoli® Storage Manager recognizes that a schedule with the same name already exists. Make one of the following choices depending on which CLIENT option is used in the HCL Workload Automation job:
  • Using the CLIENTSCHED option, the -nodel parameter can be used. If you pass it to the command, the job is deleted after its completion. If this argument is not passed to the command, the default behavior is that the Tivoli® Storage Manager schedule is deleted. This behavior is valid both when -schedname or -schedprefix is used and when the Tivoli® Storage Manager schedule name is automatically generated (no -schedname or -schedprefix are passed).
  • Using the CLIENT option, the Tivoli® Storage Manager schedule is always deleted after completion.
  • Using the CLIENTACT option, the Tivoli® Storage Manager schedule is produced automatically by Tivoli® Storage Manager itself, using an internal unique name, and it is not deleted after it has run.
How to create a job
The following sections show how to create jobs for all the classes specified in the above section. HCL Workload Automation shows standard output and return codes of the task that ran on its interfaces. Some jobs send the full job logs to the Tivoli® Storage Manager command line window, so you check the Tivoli® Storage Manager logs to verify that the commands ran successfully. The tsmxagent always returns the return code that the Tivoli® Storage Manager command line returns. If the return code is different from zero it is interpreted as an abend code. If you want to manage return codes different from zero you can change the x-agent jobs status using the RCCONDSUCC option.
Back up a database
To back up a Tivoli Storage Manager database to sequential access volumes, type the following command:
ADMIN DBBACKUP devclass=DEVCLASS [optional_parms]
where:
DEVCLASS
Specifies the name of the sequential access device class to use for the backup.
optional_parms
Specifies the optional parameters supported by the Tivoli Storage Manager.
Back up sequential volume history information
To back up sequential volume history information to one or more files, type the following command:
ADMIN VHBACKUP [optional_parms]
where:
optional_parms
Specifies the optional parameters supported by the Tivoli® Storage Manager.
Back up IBM® Tivoli® Storage Manager device information
To back up IBM® Tivoli® Storage Manager device information to one or more files, type the following command:
ADMIN DCBACKUP [optional_parms]
where:
optional_parms
Specifies the optional parameters supported by the Tivoli® Storage Manager.
Delete volume history file records
To delete volume history file records that are no longer needed (for example, records for obsolete database backup volumes), type the following command:
ADMIN DELVOLHIST type=TYPE todate=TODATE [optional_parms]
where:
TYPE
Specifies the type of records, which also meet the date and time criteria, to delete from the volume history file. You must specify the parameters in the order shown. For details about the possible values see IBM® Tivoli® Storage Manager: Administrator's Reference.
TODATE
Specifies the date to use to select sequential volume history information to be deleted. Tivoli® Storage Manager deletes only those records with a date on or before the date you specify. You can specify the date using the following format: MM/DD/YYYY.
optional_parms
Specifies the optional parameters supported by the Tivoli® Storage Manager.
Start inventory expiration processing
To start inventory expiration processing, type the following command:
ADMIN EXPIREINV [optional_parms]
where:
optional_parms
Specifies the optional parameters supported by the Tivoli® Storage Manager. For details, see IBM® Tivoli® Storage Manager: Administrator's Reference.
Run any other administrating task
To run any other administrating task:
ADMIN [TSM_command]
where:
TSM_command
Specifies the command supported by the Tivoli® Storage Manager. For details, see the IBM® Tivoli® Storage Manager Administrator's Reference.
Schedule a client backup
To schedule a client backup, type the following commands:
  • CLIENT DOMAIN SCHEDULE CLIENT [optional_parms]
    For details about optional parameters (optional_parms), see the IBM® Tivoli Storage Manager Administrator's Reference guide.
  • CLIENTSCHED -action <action name> -domain <policy domain>  
    -node <TSM node name> [-polling <value>] [-script <value>] 
    [-timeout <value>] [-schedname  TSM schedule name> | -schedprefix 
     <TSM prefix schedule name>] [-nodel] [--  <TSM options>] 
  • CLIENTACT -action <action name> [-domain <policy domain> ] 
    [-node <TSM node name>] [-script <value>] [--  <TSM options>]