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.

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