DEFINE CLIENTACTION (Define a one-time client action)

Use this command to schedule one or more clients to process a command for a one-time action.

The server automatically defines a schedule and associates the client node to the schedule. The server assigns the schedule priority 1, sets the PERUNITS to ONETIME, and determines the number of days to keep the schedule active. The number of days is based on the value set with the SET CLIENTACTDURATION command.

How quickly the client processes this command depends on whether the scheduling mode for the client is set to server-prompted or client-polling. The client scheduler must be started on the client workstation in order for the server to process the schedule.

Remember: The start of the Tivoli® Storage Manager scheduler depends on the processing of other threads in the server and other processes on the Tivoli Storage Manager server host system. The amount of time it takes to start the scheduler also depends on network traffic and how long it takes to open a socket, to connect with the Tivoli Storage Manager client, and to receive a response from the client. In general, the greater the processing and connectivity requirements on the Tivoli Storage Manager server and client, the longer it can take to start the scheduler.

Privilege class

To issue this command, you must have system privilege, unrestricted policy privilege, or restricted policy for the policy domain to which the schedule belongs.

Syntax


                           .-,---------.     
                           V           |     
>>- DEFine CLIENTAction------node_name-+------------------------>

   .-DOmain--=--*---------------.   
>--+----------------------------+------------------------------->
   |            .-,-----------. |   
   |            V             | |   
   '-DOmain--=----domain_name-+-'   

   .-ACTion--=--Incremental------------------------------------.   
>--+-----------------------------------------------------------+-->
   '-ACTion--=--+-Incremental--------------------------------+-'   
                +-Selective----------------------------------+     
                +-Archive--+-------------------------------+-+     
                |          |               .-""----------. | |     
                |          '-SUBACTion--=--+-------------+-' |     
                |                          +-FASTBack----+   |     
                |                          +-SYSTEMSTate-+   |     
                |                          '-VM----------'   |     
                +-Backup--+-------------------------------+--+     
                |         |               .-""----------. |  |     
                |         '-SUBACTion--=--+-------------+-'  |     
                |                         +-FASTBack----+    |     
                |                         +-SYSTEMSTate-+    |     
                |                         '-VM----------'    |     
                +-REStore------------------------------------+     
                +-RETrieve-----------------------------------+     
                +-IMAGEBACkup--------------------------------+     
                +-IMAGEREStore-------------------------------+     
                +-Command------------------------------------+     
                '-Macro--------------------------------------'     

>--+---------------------------+-------------------------------->
   '-OPTions--=--option_string-'   

                                  .-Wait--=--No------.   
>--+---------------------------+--+------------------+---------><
   '-OBJects--=--object_string-'  '-Wait--=--+-No--+-'   
                                             '-Yes-'

Parameters

node_name (Required)

Specifies the name of the client node that will process the schedule associated with the action. If you specify multiple node names, separate the names with commas; do not use intervening spaces. You can use the asterisk wildcard character to specify multiple names.

DOmain

Specifies the list of policy domains used to limit the list of client nodes. Only client nodes that are assigned to one of the specified policy domains will be scheduled. All clients assigned to a matching domain will be scheduled. Separate multiple domain names with commas and no intervening spaces. If you do not specify a value, all policy domains will be included in the list.

ACTion

Specifies the action that occurs when this schedule is processed. Possible values are:

Incremental

Specifies that the schedule backs up all files that are new or that have changed since the last incremental backup. Incremental also backs up any file for which all existing backups might have expired.

Selective

Specifies that the schedule backs up only files that are specified with the OBJECTS parameter.

Archive

Specifies that the schedule archives files that are specified with the OBJECTS parameter.

Backup

Specifies that the schedule backs up files that are specified with the OBJECTS parameter.

REStore

Specifies that the schedule restores files that are specified with the OBJECTS parameter.

When you specify ACTION=RESTORE for a scheduled operation, and the REPLACE option is set to PROMPT, no prompting occurs. If you set the option to PROMPT, the files are skipped.

If you specify a second file specification, this second file specification acts as the restore destination. If you need to restore multiple groups of files, schedule one for each file specification that you need to restore.

RETrieve

Indicates that the schedule retrieves files that are specified with the OBJECTS parameter.

Remember: A second file that is specified acts as the retrieve destination. If you need to retrieve multiple groups of files, create a separate schedule for each group of files.

IMAGEBACkup

Specifies that the schedule backs up logical volumes that are specified with the OBJECTS parameter.

IMAGEREStore

Specifies that the schedule restores logical volumes that are specified with the OBJECTS parameter.

Command

Specifies that the schedule processes a client operating system command or script that is specified with the OBJECTS parameter.

Macro

Specifies that a client processes a macro whose file name is specified with the OBJECTS parameter.

SUBACTion

You can specify one of the following values:

"": When a null string (two double quotes) is specified with ACTION=BACKUP the backup is an incremental.
FASTBAck: Specifies that a FastBack client operation that is identified by the ACTION parameter is to be scheduled for processing. The ACTION parameter must be either ARCHIVE or BACKUP.
SYSTEMSTate: Specifies that a client Systemstate backup is scheduled.
VApp: Specifies that a client vApp backup is scheduled. A vApp is a collection of pre-deployed virtual machines.
VM: Specifies that a client VMware backup operation is scheduled.

OPTions

Specifies the client options that you specify to the scheduled command at the time the schedule is processed. This parameter is optional.

Only those options that are valid on the scheduled command can be specified for this parameter. Refer to the appropriate client manual for information about options that are valid from the command line. All options described there as valid only on the initial command line result in an error or are ignored when running the schedule from the server. For example, do not include the following options because they have no impact when the client processes the scheduled command:

MAXCMDRETRIES
OPTFILE
QUERYSCHEDPERIOD
RETRYPERIOD
SCHEDLOGNAME
SCHEDMODE
SERVERNAME
TCPCLIENTADDRESS
TCPCLIENTPORT

Windows operating systems When you define a scheduler service by using the DSMCUTIL command or the backup-archive client GUI wizard, you specify an options file. You cannot override the options in that options file by issuing the scheduled command. You must modify the options in your scheduler service.

If the option string contains multiple options or options with embedded spaces, surround the entire option string with one pair of apostrophes. Enclose individual options that contain spaces in quotation marks. A leading minus sign is required in front of the option. Errors can occur if the option string contains spaces that are not quoted correctly.

The following examples show how to specify some client options:

To specify subdir=yes and domain all-local -systemobject, enter:
- options='-subdir=yes -domain="all-local -c: -systemobject"'
To specify domain all-local -c: -d:, enter:
- options='-domain="all-local -c: -d:"'

Tip: For Windows clients running in batch mode, if the use of quotation marks is necessary, use interactive mode or operating system escape characters. For additional information, see:

OBJects

Specifies the objects for which the specified action is performed. Use a single space between each object. This parameter is required except when ACTION=INCREMENTAL. If the action is a backup, archive, retrieve, or restore operation, the objects are file spaces, directories, or logical volumes. If the action is to run a command or macro, the object is the name of the command or macro to run.

When you specify ACTION=INCREMENTAL without specifying a value for this parameter, the scheduled command is invoked without specified objects and attempts to process the objects as defined in the client option file. To select all file spaces or directories for an action, explicitly list them in the object string. Entering only an asterisk in the object string causes the backup to occur only for the directory where the scheduler was started.

Important:

If you specify a second file specification, and it is not a valid destination, you receive this error:
```
ANS1082E Invalid destination file specification <filespec> entered.
```

If you specify more than two file specifications, you receive this error:

ANS1102E Excessive number of command line arguments passed to the 
program!

When you specify ACTION=ARCHIVE, INCREMENTAL, or SELECTIVE for this parameter, you can list a maximum of twenty (20) file specifications.

Enclose the object string in double quotes if it contains blank characters (spaces), and then surround the double quotes with single quotes. If the object string contains multiple file names, enclose each file name with its own pair of double quotes, then surround the entire string with one pair of single quotes. Errors can occur if file names contain a space that is not quoted correctly.

If you are using characters that have a special meaning for Windows users, such as commas, surround the entire argument in two pairs of double quotes, then surround the entire string with single quotes. The following examples show you how to specify some file names:

To specify C:\FILE 2, D:\GIF FILES, and E:\MY TEST FILE, enter:
- OBJECTS='"C:\FILE 2" "D:\GIF FILES" "E:\MY TEST FILE"'
To specify D:\TEST FILE, enter:
- OBJECTS='"D:\TEST FILE"'
To specify D:TEST,FILE:
- OBJECTS='""D:\TEST,FILE""'

The following examples show how to specify some file names:

To specify /home/file 2, /home/gif files, and /home/my test file, enter:
- OBJECTS='"/home/file 2" "/home/gif files" "/home/my test file"'
To specify /home/test file, enter:
- OBJECTS='"/home/test file"'

The following examples show how to specify some file names:

To specify /opt/file 2, /opt/gif files, and /opt/my test file, enter:
- OBJECTS='"/opt/file 2" "/opt/gif files" "/opt/my test file"'
To specify /opt/test file, enter:
- OBJECTS='"/opt/test file"'

The following examples show how to specify some file names:

To specify /usr/file 2, /usr/gif files, and /usr/my test file, enter:
- OBJECTS='"/usr/file 2" "/usr/gif files" "/usr/my test file"'
To specify /usr/test file, enter:
- OBJECTS='"/usr/test file"'

Tip: For Windows clients running in batch mode, if the use of double quotes is necessary, use interactive mode or operating system escape characters. For additional information, see:

Wait

Specifies whether to wait for a scheduled client operation to complete. This parameter is useful when defining client actions from a command script or macro. This parameter is optional. The default is No. Possible values are:

No

Specifies that you do not wait for the scheduled client operation to complete. If you specify this value and the value of the ACTION parameter is COMMAND, the return code indicates whether the client action was defined.

Yes

Specifies that you wait for the scheduled client operation to complete. If you specify this value and the value of the ACTION parameter is COMMAND, the return code indicates the status of the client operation.

You cannot issue the DEFINE CLIENTACTION command with WAIT=YES from the server console. However, from the server console, you can:

Specify WAIT=YES with DEFINE CLIENTACTION as the command line of a DEFINE SCRIPT command.
Specify WAIT=YES with DEFINE CLIENTACTION as the command line of a file whose contents will be read into the script that is defined by a DEFINE SCRIPT command.

Restriction: If you specify the DEFINE CLIENTACTION command with WAIT=YES in a macro, the immediate schedules defined by the command will not roll back if the macro does not complete successfully.

Example: Perform a one-time incremental backup

Issue an incremental backup command for client node TOM assigned to policy domain EMPLOYEE_RECORDS. Tivoli Storage Manager defines a schedule and associates the schedule to client node TOM (assuming that the client scheduler is running).

define clientaction tom domain=employee_records 
action=incremental

Related commands

Table 1. Commands related to DEFINE CLIENTACTION
Command	Description
DELETE SCHEDULE	Deletes a schedule from the database.
QUERY ASSOCIATION	Displays the clients associated with one or more schedules.
QUERY EVENT	Displays information about scheduled and completed events for selected clients.
QUERY SCHEDULE	Displays information about schedules.
SET CLIENTACTDURATION	Specifies the duration of a schedule defined using the DEFINE CLIENTACTION command.