DEFINE SCHEDULE (Define a schedule for an administrative command)

Use the DEFINE SCHEDULE command to create a new schedule for processing an administrative command.

You can include scripts in an administrative command schedule so the commands are processed automatically.
Note:
  1. You cannot schedule the MACRO command or the QUERY ACTLOG command.
  2. If you are scheduling a command that specifies the WAIT parameter, the parameter must be set to YES in order for the process to provide a return code to the session that started it. For more information about the WAIT parameter, see Server command processing.

Privilege class

To define an administrative command schedule, you must have system privilege.

Syntax

Read syntax diagramSkip visual syntax diagram
Classic administrative schedule

>>-DEFine SCHedule--schedule_name------------------------------->

>--+-------------------------+--CMD--=--command----------------->
   '-Type--=--Administrative-'                    

   .-ACTIVE--=--No--.                                    
>--+----------------+--+-----------------------------+---------->
   '-ACTIVE--=--Yes-'  '-DESCription--=--description-'   

   .-PRIority--=--5------.  .-STARTDate--=--current_date-.   
>--+---------------------+--+----------------------------+------>
   '-PRIority--=--number-'  '-STARTDate--=--date---------'   

   .-STARTTime--=--current_time-.  .-DURation--=--1------.   
>--+----------------------------+--+---------------------+------>
   '-STARTTime--=--time---------'  '-DURation--=--number-'   

   .-DURUnits--=--Hours----------.  .-MAXRUNtime--=--0------.   
>--+-----------------------------+--+-----------------------+--->
   '-DURUnits--=--+-Minutes----+-'  '-MAXRUNtime--=--number-'   
                  +-Hours------+                                
                  +-Days-------+                                
                  '-INDefinite-'                                

   .-SCHEDStyle--=--Classic-.  .-PERiod--=--1------.   
>--+------------------------+--+-------------------+------------>
   '-SCHEDStyle--=--Classic-'  '-PERiod--=--number-'   

   .-PERUnits--=--Days--------.   
>--+--------------------------+--------------------------------->
   '-PERUnits--=--+-Hours---+-'   
                  +-Days----+     
                  +-Weeks---+     
                  +-Months--+     
                  +-Years---+     
                  '-Onetime-'     

   .-DAYofweek--=--ANY-----------.   
>--+-----------------------------+------------------------------>
   '-DAYofweek--=--+-ANY-------+-'   
                   +-WEEKDay---+     
                   +-WEEKEnd---+     
                   +-SUnday----+     
                   +-Monday----+     
                   +-TUesday---+     
                   +-Wednesday-+     
                   +-THursday--+     
                   +-Friday----+     
                   '-SAturday--'     

   .-EXPiration--=--Never-----.   
>--+--------------------------+--------------------------------><
   '-EXPiration--=--+-Never-+-'   
                    '-date--'     

Syntax

Read syntax diagramSkip visual syntax diagram
Enhanced administrative schedule

>>-DEFine SCHedule--schedule_name------------------------------->

>--+-------------------------+--CMD--=--Command----------------->
   '-Type--=--Administrative-'                    

   .-ACTIVE--=--NO--.                                    
>--+----------------+--+-----------------------------+---------->
   '-ACTIVE--=--YES-'  '-DESCription--=--description-'   

   .-PRIority--=--5------.  .-STARTDate--=--current_date-.   
>--+---------------------+--+----------------------------+------>
   '-PRIority--=--number-'  '-STARTDate--=--date---------'   

   .-STARTTime--=--current_time-.  .-DURation--=--1------.   
>--+----------------------------+--+---------------------+------>
   '-STARTTime--=--time---------'  '-DURation--=--number-'   

   .-DURUnits--=--Hours-------.  .-MAXRUNtime--=--0------.   
>--+--------------------------+--+-----------------------+------>
   '-DURUnits--=--+-Minutes-+-'  '-MAXRUNtime--=--number-'   
                  +-Hours---+                                
                  '-Days----'                                

                            .-MONth--=--ANY-----------.   
>--SCHEDStyle--=--Enhanced--+-------------------------+--------->
                            '-MONth--=--+-ANY-------+-'   
                                        +-JAnuary---+     
                                        +-February--+     
                                        +-MARch-----+     
                                        +-APril-----+     
                                        +-May-------+     
                                        +-JUNe------+     
                                        +-JULy------+     
                                        +-AUgust----+     
                                        +-September-+     
                                        +-October---+     
                                        +-November--+     
                                        '-December--'     

   .-DAYOFMonth--=--ANY-----.  .-WEEKofmonth--=--ANY--------.   
>--+------------------------+--+----------------------------+--->
   '-DAYOFMonth--=--+-ANY-+-'  '-WEEKofmonth--=--+-ANY----+-'   
                    '-Day-'                      +-FIrst--+     
                                                 +-Second-+     
                                                 +-Third--+     
                                                 +-FOurth-+     
                                                 '-Last---'     

   .-DAYofweek--=--ANY-----------.   
>--+-----------------------------+------------------------------>
   '-DAYofweek--=--+-ANY-------+-'   
                   +-WEEKDay---+     
                   +-WEEKEnd---+     
                   +-SUnday----+     
                   +-Monday----+     
                   +-TUesday---+     
                   +-Wednesday-+     
                   +-THursday--+     
                   +-Friday----+     
                   '-SAturday--'     

   .-EXPiration--=--Never-----.   
>--+--------------------------+--------------------------------><
   '-EXPiration--=--+-Never-+-'   
                    '-date--'     

Parameters

schedule_name (Required)
Specifies the name of the schedule to be defined. You can specify up to 30 characters for the name.
Type=Administrative
Specifies that a schedule for an administrative command is defined. This parameter is optional. An administrative command is assumed if the CMD parameter is specified.
CMD (Required)
Specifies the administrative command to schedule for processing. The maximum length of the command is 512 characters. Enclose the administrative command in quotation marks if it contains any blank characters.
Restriction: You cannot specify redirection characters with this parameter.
ACTIVE
Specifies whether Tivoli Storage Manager processes an administrative command schedule when the startup window occurs. This parameter is optional. The default is NO. The administrative command schedule must be set to the active state with the UPDATE SCHEDULE command so that Tivoli Storage Manager can process the schedule. Possible values are:
YES
Specifies that Tivoli Storage Manager processes an administrative command schedule when the startup window begins.
NO
Specifies that Tivoli Storage Manager does not process an administrative command schedule when the startup window begins.
DESCription
Specifies a description of the schedule. This parameter is optional. You can specify up to 255 characters for the description. Enclose the description in quotation marks if it contains any blank characters.
PRIority
Specifies the priority value for a schedule. This parameter is optional. You can specify an integer from 1 to 10, with 1 being the highest priority and 10 being the lowest. The default is 5.

If two or more schedules have the same window start time, the value you specify determines when Tivoli Storage Manager processes the schedule. The schedule with the highest priority starts first. For example, a schedule with PRIORITY=3 starts before a schedule with PRIORITY=5.

STARTDate
Specifies the date for the beginning of the window in which the schedule is first processed. This parameter is optional. The default is the current date. Use this parameter with the STARTTIME parameter to specify when the initial startup window of the schedule starts.
You can specify the date using one of the values below:
Value Description Example
MM/DD/YYYY A specific date 09/15/1998
TODAY The current date TODAY
TODAY+days or +days The current date plus days specified. The maximum number of days you can specify is 9999. TODAY +3 or +3.
EOLM (End Of Last Month) The last day of the previous month. EOLM
EOLM-days The last day of the previous month minus days specified. EOLM-1

To include files that were active a day before the last day of the previous month.

BOTM (Beginning Of This Month) The first day of the current month. BOTM
BOTM+days The first day of the current month, plus days specified. BOTM+9

To include files that were active on the 10th day of the current month.

STARTTime
Specifies the time for the beginning of the window in which the schedule is first processed. This parameter is optional. The default is the current time. This parameter is used in conjunction with the STARTDATE parameter to specify when the initial startup window begins.
You can specify the time using one of the values below:
Value Description Example
HH:MM:SS A specific time 10:30:08
NOW The current time NOW
NOW+HH:MM or +HH:MM The current time plus hours and minutes specified NOW+02:00 or +02:00.

If you issue this command at 5:00 with STARTTIME=NOW+02:00 or STARTTIME=+02:00, the beginning of the startup window is at 7:00.

NOW-HH:MM or -HH:MM The current time minus hours and minutes specified NOW-02:00 or -02:00.

If you issue this command at 5:00 with STARTTIME=NOW-02:00 or STARTTIME=-02:00, the beginning of the startup window is at 3:00.

DURation
Specifies the number of units that define the length of the startup window of the scheduled operation. This parameter is optional. This value must be from 1 to 999. The default is 1.

Use this parameter with the DURUNITS parameter to specify the length of the startup window. For example, if you specify DURATION=20 and DURUNITS=MINUTES, the schedule must be started within 20 minutes of the start date and start time. The default length of the startup window is 1 hour. The duration of the window must be shorter than the period between windows.

This value is ignored if you specify DURUNITS=INDEFINITE.

DURUnits
Specifies the time units used to determine the duration of the window in which the schedule can start. This parameter is optional. The default is HOURS.

Use this parameter with the DURATION parameter to specify how long the startup window remains open to process the schedule. For example, if DURATION=20 and DURUNITS=MINUTES, the schedule must be started within 20 minutes of the start date and start time. The schedule may not necessarily complete processing within this window. If the schedule needs to be retried for any reason, the retry attempts must begin before the startup window elapses, or the operation does not restart.

The default value for the length of the startup window is 1 hour. You can specify one of the following values: :
Minutes
Specifies that the duration of the window is defined in minutes.
Hours
Specifies that the duration of the window is defined in hours.
Days
Specifies that the duration of the window is defined in days.
INDefinite
Specifies that the startup window of the scheduled operation has an indefinite duration. The schedule can run any time after the scheduled start time, until the schedule expires. You cannot specify DURUNITS=INDEFINITE, unless you specify PERUNITS=ONETIME. The INDEFINITE value is not allowed with enhanced schedules.
MAXRUNtime
Specifies the maximum run time, which is the number of minutes during which server processes that are started by the scheduled commands must be completed. If processes are still running after the maximum run time, the central scheduler cancels the processes.
Tips:
  • The processes might not end immediately when the central scheduler cancels them; they end when they register the cancellation notification from the central scheduler.
  • The maximum run time is calculated beginning from when the server process starts. If the schedule command starts more than one process, each process maximum run time is calculated from when the process starts.
  • This parameter does not apply to some processes, such as duplicate-identification processes, which can continue to run after the maximum run time.
  • This parameter does not apply if the scheduled command does not start a server process.
  • Another cancel time might be associated with some commands. For example, the MIGRATE STGPOOL command can include a parameter that specifies the length of time that the storage pool migration runs before the migration is automatically canceled. If you schedule a command for which a cancel time is defined, and you also define a maximum run time for the schedule, the processes are canceled at whichever cancel time is reached first.
Restrictions:
  • The value of the parameter is not distributed to servers that are managed by an enterprise configuration manager.
  • The value of the parameter is not exported by the EXPORT command.

The parameter is optional. You can specify a number in the range 0-1440. The default value is 0. A value of 0 means that the maximum run time is indefinite, and the central scheduler does not cancel processes. The maximum run time must be greater than the startup window duration, which is defined by the DURATION and DURUNITS parameters.

For example, if the start time of a scheduled command is 9:00 PM, and the duration of the startup window is 2 hours, the startup window is 9:00 PM - 11:00 PM. If the maximum run time is 240 minutes, that is, 4 hours, all applicable server processes that are started by the command must be completed by 1:00 AM. If one or more applicable processes are still running after 1:00 AM, the central scheduler cancels the processes.
Tip: Alternatively, you can specify an end time of 1:00 AM in the Tivoli Storage Manager Operations Center.
SCHEDStyle
This parameter is optional. SCHEDSTYLE defines either the interval between times when a schedule should run, or the days on which it should run. The style can be either classic or enhanced. The default is the classic syntax.

For classic schedules, these parameters are allowed: PERIOD, PERUNITS, and DAYOFWEEK. Not allowed for classic schedules are: MONTH, DAYOFMONTH, and WEEKOFMONTH.

For enhanced schedules, these parameters are allowed: MONTH, DAYOFMONTH, WEEKOFMONTH, and DAYOFWEEK. These parameters are not allowed: PERIOD and PERUNITS.

PERiod
Specifies the length of time between startup windows for this schedule. This parameter is optional. This parameter is used only with classic schedules. You can specify an integer from 1 to 999. The default is 1.

Use this parameter with the PERUNITS parameter to specify the period between startup windows. For example, if you specify PERIOD=5 and PERUNITS=DAYS (assuming that DAYOFWEEK=ANY), the operation is scheduled every five days after the initial start date and start time. The period between startup windows must exceed the duration of each window. The default is 1 day.

This value is ignored if you specify PERUNITS=ONETIME.

PERUnits
Specifies the time units used to determine the period between startup windows for this schedule. This parameter is optional. This parameter is used only with classic schedules. The default is DAYS.
Use this parameter with the PERIOD parameter to specify the period between startup windows. For example, if you specify PERIOD=5 and PERUNITS=DAYS (assuming that DAYOFWEEK=ANY), the operation is scheduled every 5 days after the initial start date and start time. The default is 1 day. You can specify one of the following values: :
Hours
Specifies that the time between startup windows is in hours.
Days
Specifies that the time between startup windows is in days.
Weeks
Specifies that the time between startup windows is in weeks.
Months
Specifies that the time between startup windows is in months.

When you specify PERUNITS=MONTHS, the scheduled operation will be processed each month on the same date. For example, if the start date for the scheduled operation is 02/04/1998, the schedule will process on the 4th of every month thereafter. However, if the date is not valid for the next month, then the scheduled operation will be processed on the last valid date in the month. Thereafter, subsequent operations are based on this new date. For example, if the start date is 03/31/1998, the next month's operation will be scheduled for 04/30/1998. Thereafter, all subsequent operations will be on the 30th of the month until February. Because February has only 28 days, the operation will be scheduled for 02/28/1999. Subsequent operations will be processed on the 28th of the month.

Years
Specifies that the time between startup windows for the schedule is in years.

When you specify PERUNITS=YEARS, the scheduled operation will be processed on the same month and date of each year. For example, if the start date for the scheduled operation is 02/29/2004, the next year's scheduled operation will be 02/28/2005 because February only has 28 days. Thereafter, subsequent operations will be scheduled for February 28th.

Onetime
Specifies that the schedule processes once. This value overrides the value you specified for the PERIOD parameter.
DAYofweek
Specifies the day of the week on which the startup window for the schedule begins. This parameter is optional. You can specify different options for the DAYofweek parameter, depending on whether the schedule style was defined as Classic or Enhanced:
Classic Schedule
Specifies the day of the week on which the startup window for the schedule begins. This parameter is optional. You can either specify one day of the week, or WEEKDAY, WEEKEND, or ANY. If the start date and start time fall on a day that does not correspond to a day you specify, the start date and start time will be shifted forward in 24-hour increments until the DAYOFWEEK parameter is satisfied.

If you select a value for DAYOFWEEK other than ANY, and depending on the values for PERIOD and PERUNITS, schedules may not be processed when you would expect. The default is ANY.

Enhanced Schedule
Specifies the days of the week on which to run the schedule. You can either specify multiple days separated by commas and no intervening blanks, or WEEKDAY, WEEKEND, or ANY. If you specify multiple days, the schedule will run on each of the specified days. If you specify WEEKDAY or WEEKEND, you must also specify either WEEKOFMONTH=FIRST or WEEKOFMONTH=LAST, and the schedule will run just once per month.

The default value is ANY, meaning the schedule will run every day of the week or on the day or days determined by other enhanced schedule parameters. DAYOFWEEK must have a value of ANY (either by default or specified with the command) when used with the DAYOFMONTH parameter.

Possible values for the DAYofweek parameter are:
ANY
Specifies that the startup window can begin on any day of the week.
WEEKDay
Specifies that the startup window can begin on Monday, Tuesday, Wednesday, Thursday, or Friday.
WEEKEnd
Specifies that the startup window can begin on Saturday or Sunday.
SUnday
Specifies that the startup window begins on Sunday.
Monday
Specifies that the startup window begins on Monday.
TUesday
Specifies that the startup window begins on Tuesday.
Wednesday
Specifies that the startup window begins on Wednesday.
THursday
Specifies that the startup window begins on Thursday.
Friday
Specifies that the startup window begins on Friday.
SAturday
Specifies that the startup window begins on Saturday.
MONth
Specifies the months of the year during which to run the schedule. This parameter is used only with enhanced schedules. Specify multiple values by using commas and no intervening blanks. The default value is ANY. This means the schedule will run during every month of the year.
DAYOFMonth
Specifies the day of the month to run the schedule. This parameter is used only with enhanced schedules. You can either specify ANY or a number from -31 through 31, excluding zero. Negative values are a day from the end of the month, counting backwards. For example, the last day of the month is -1, the next-to-the-last day of the month is -2, etc. You can specify multiple values separated by commas and no intervening blanks. If you specify multiple values, the schedule will run on each of the specified days of the month. If multiple values resolve to the same day, the schedule will run only once that day.

The default value is ANY This means the schedule will run on every day of the month or on the days determined by other enhanced schedule parameters. DAYOFMONTH must have a value of ANY (either by default or specified with the command) when used with the DAYOFWEEK or WEEKOFMONTH parameters.

WEEKofmonth
Specifies the week of the month in which to run the schedule. This parameter is used only with enhanced schedules. A week is considered any seven-day period which does not start on a particular day of the week. You can specify FIRST, SECOND, THIRD, FOURTH, LAST, or ANY. You can specify multiple values separated by commas and no intervening blanks. If you specify multiple values, the schedule will run during each of the specified weeks of the month. If multiple values resolve to the same week, the schedule will run only once during that week.

The default value is ANY, meaning the schedule will run during every week of the month or on the day or days determined by other enhanced schedule parameters. WEEKOFMONTH must have a value of ANY (either by default or specified with the command) when used with the DAYOFMONTH parameter.

EXPiration
Specifies the date after which this schedule is no longer used. This parameter is optional. The default is NEVER. You can specify one of the following values: :
Never
Specifies that the schedule never expires.
expiration_date
Specifies the date on which this schedule expires, in MM/DD/YYYY format. If you specify an expiration date, the schedule expires at 23:59:59 on the date you specify.

Example: Define a schedule to back up the primary storage pool every two days

Define a schedule named BACKUP_ARCHIVEPOOL that backs up the primary storage pool ARCHIVEPOOL to the copy storage pool RECOVERYPOOL. The backup runs at 8 p.m. every two days.
define schedule backup_archivepool type=administrative 
cmd="backup stgpool archivepool recoverypool" 
active=yes starttime=20:00 period=2

Example: Define a schedule to back up the primary storage pool twice a month

Define a schedule named BACKUP_ARCHIVEPOOL that backs up the primary storage pool ARCHIVEPOOL to the copy storage pool RECOVERYPOOL. Select an enhanced schedule and run on the first and fifteenth day of the month.
define schedule backup_archivepool type=administrative 
cmd="backup stgpool archivepool recoverypool" 
schedstyle=enhanced dayofmonth=1,15