HCL Workload Automation, Version 9.4

Run cycle group definition

A run cycle group is a database object within which one or more run cycles is defined. The run cycles combined together produce a set of run dates for a job stream. A run cycle group can contain:
  • Inclusive run cycles that specify when a job stream must run. The keywords defining the run cycle follow the on keyword.
  • Exclusive run cycles that specify when a job stream is not to run. The keywords defining the run cycle follow the except keyword. Usually an exclusive run cycle is matched against an inclusive one to define specific dates when the job stream is exempted from running.

Each of the run cycles includes its own definition keywords. Some of these keywords can also be defined at run cycle group-level. When a run cycle and the run cycle group include the same keyword, the value in the run cycle definition is used for the run cycle. When the run cycle definition omits a certain keyword that is defined at run cycle group-level, it inherits the value.

Each run cycle group definition has the following format and arguments:

Syntax

$runcyclegroup
runcyclegroupname [“description”]
     vartable tablename
       [freedays calendarname [-sa] [-su]]
[on [runcycle name
       [validfrom date] [validto date]
       [descriptiontext”]
       [vartable table_name]]
      {date|day|calendar|request|”icalendar”} [,...]
       [fdignore|fdnext|fdprev][subset subsetname AND|OR]
       [({at time [+n day[s]] |
       schedtime time [+n day[s]]}
       [until | jsuntil time [timezone|tz tzname][+n day[s]]
        [onuntilaction]]
       [every rate {everyendtime time[+n day[s]]}
       [deadline time [+n day[s]]])]]
    [,...]]
    [except [runcycle name]
          [validfrom date] [validto date]
          [descriptiontext”]
          {date|day|calendar|request|”icalendar”} [,...]
          [fdignore|fdnext|fdprev][subset subsetname AND|OR]  
          [{(at time [+n day[s]])] |
          (schedtime time [+n day[s]])}]
    [,...]
    [{at time [timezone|tz tzname] [+n day[s]] |
    schedtime time [timezone|tz tzname] [+n day[s]]}]
   [until | jsuntil time [timezone|tz tzname][+n day[s]] [onuntilaction]]
    [every rate {everyendtime time[+n day[s]]}]
    [deadline time [timezone|tz tzname] [+n day[s]]]
end

Arguments

runcyclegroupname
Specifies the name of the run cycle group. The name can contain up to eight alphanumeric characters, including dashes (-) and underscores (_), and must start with a letter.
description
Provides a description of the run cycle group. The description can contain up to 120 alphanumeric characters. It must be enclosed in double quotation marks. It can contain alphanumeric characters as long as it starts with a letter. It can contain the following characters: comma (,), period (.), dash (-), plus (+), single quote ('), and equal (=). It cannot contain double quotation marks (") other than the enclosing ones, colon (:), semi-colon (;), and ampersand (&).
vartable tablename
The name of the variable table. The name must start with a letter, and can contain alphanumeric characters, dashes, and underscores. It can contain up to 80 characters.
[freedays Calendar_Name [-sa] [-su]]
Specifies a freeday calendar for calculating workdays for the job stream. It can also set Saturdays and Sundays as workdays.
Calendar_Name
The name of the calendar that must be used as the non-working days calendar for the job stream. If Calendar_Name is not in the database, HCL Workload Automation issues a warning message when you save the job stream. If Calendar_Name is not in the database when the command schedulr runs, HCL Workload Automation issues an error message and uses the default calendar holidays in its place. Do not use the names of weekdays for the calendar names.
-sa
Saturdays are workdays.
-su
Sundays are workdays.
See freedays for details and examples.
runcycle name
Specifies a label with a friendly name for the run cycle specified in the following lines.
valid from date ... valid to date
Delimits the time frame during which the job stream is active, that is the job stream is added to the production plan. Note that the date specified as valid to value is not included in the run cycle, therefore on this date the job stream is not active.
description ”text
Contains a description of the run cycle.
vartable
Specifies the name of the variable table to be used by the run cycle.
date
Specifies a run cycle that runs on specific dates. The syntax used for this type is:

yyyymmdd [,yyyymmdd][,...]

For example, for a job stream that is scheduled to run on the 25th of May 2009 and on the 12th of June 2009 the value is:
on
20090525,20090612
day
Specifies a run cycle that runs on specific days. The syntax used for this type is:

{mo|tu|we|th|fr|sa|su}

For example, for a job stream that is scheduled to run every Monday the value is:
on
mo
calendar
The dates specified in a calendar with this name. The calendar name can be followed by an offset in the following format:

{+ | -}n {day[s] | weekday[s] | workday[s]}

Where:

n
The number of days, weekdays, or workdays.
days
Every day of the week.
weekdays
Every day of the week, except Saturday and Sunday.
workdays
Every day of the week, except for Saturdays and Sundays (unless otherwise specified with the freedays keyword) and for the dates marked either in a designated non-working days calendar or in the holidays calendar.
request
Selects the job stream only when requested. This is used for job streams that are selected by name rather than date. To prevent a scheduled job stream from being selected for JnextPlan, change its definition to ON REQUEST.
Note: When attempting to run a job stream that contains "on request" times, consider that:
  • "On request" always takes precedence over "at".
  • "On request" never takes precedence over "on".
icalendar
Represents a standard used to specify a recurring rule that describes when a job stream runs.

The syntax used for run cycle with type icalendar is the following:

FREQ={DAILY|WEEKLY|MONTHLY|YEARLY}

[;INTERVAL=[-]n]

[;{BYFREEDAY|BYWORKDAY|BYDAY=weekday_list|

BYMONTHDAY=monthday_list}]

where the default value for keyword INTERVAL is 1.

Using icalendar you can specify that a job stream runs:
every n days
by using the following format:

FREQ=DAILY[;INTERVAL=n]

where the value set for valid from is the first day of the resulting dates.

For example, for a job stream that is scheduled to run daily the value is:
FREQ=DAILY
For a job stream that is scheduled to run every second day the value is:
FREQ=DAILY;INTERVAL=2
every free or work days
by using the following format:

FREQ=DAILY[;INTERVAL=n]

;BYFREEDAY|BYWORKDAY

For example, for a job stream that is scheduled to run every non-working day the value is:
FREQ=DAILY;BYFREEDAY
For a job stream that is scheduled to run every second workday the value is:
FREQ=DAILY;INTERVAL=2;BYWORKDAY
every n weeks on specific weekdays
by using the following format:

FREQ=WEEKLY[;INTERVAL=n]

;BYDAY=weekday_list

where the value set for weekday_list is
[SU][,MO][,TU][,WE][,TH][,FR][,SA]
For example, for a job stream that is scheduled to run every week on Friday and Saturday the value is:
FREQ=WEEKLY;BYDAY=FR,SA
For a job stream that is scheduled to run every three weeks on Friday the value is:
FREQ=WEEKLY;INTERVAL=3;BYDAY=FR
every n months on specific dates of the month
by using the following format:

FREQ=MONTHLY[;INTERVAL=n]

;BYMONTHDAY=monthday_list

where the value set for monthday_list is represented by a list of
[+number_of_day_from_beginning_of_month]
[-number_of_day_from_end_of_month]
[number_of_day_of_the_month]
For example, for a job stream that is scheduled to run monthly on the 27th day the value is:
FREQ=MONTHLY;BYMONTHDAY=27
For a job stream that is scheduled to run every six months on the 15th and on the last day of the month the value is:
FREQ=MONTHLY;INTERVAL=6;BYMONTHDAY=15,-1
every n months on specific days of specific weeks
by using the following format:

FREQ=MONTHLY[;INTERVAL=n]

;BYDAY=day_of_m_week_list

where the value set for day_of_m_week_list is represented by a list of
[+number_of_week_from_beginning_of_month]
[-number_of_week_from_end_of_month]
[weekday]
For example, for a job stream that is scheduled to run monthly on the first Monday and on the last Friday the value is:
FREQ=MONTHLY;BYDAY=1MO,-1FR
For a job stream that is scheduled to run every six months on the 2nd Tuesday the value is:
FREQ=MONTHLY;INTERVAL=6;BYDAY=2TU
every n years
by using the following format:

FREQ=YEARLY[;INTERVAL=n]

where the value set for valid from is the first day of the resulting dates.

For example, for a job stream that is scheduled to run yearly the value is:
FREQ=YEARLY
For a job stream that is scheduled to run every two years the value is:
FREQ=YEARLY;INTERVAL=2
Note: The following limitations apply:
  • the maximum supported interval for a daily run cycle is 31 days.
  • the maximum supported interval for a weekly run cycle is 8 weeks.
  • the maximum supported interval for a monthly run cycle is 12 months. For run cycles specifying the day of the week based on the month, for example the third Saturday or the second Friday, the maximum supported interval is 5 days.
  • the maximum supported interval for a yearly run cycle is 10 years.
fdignore|fdnext|fdprev
Indicates the rule to be applied if the date selected for running the job or job stream falls on a non-working day. The available settings are:
fdignore
Do not add the date.
fdnext
Add the nearest workday after the non-working day.
fdprev
Add the nearest workday before the non-working day.
[subset subsetname AND|OR]
subset subsetname
Specifies the name of the subset. If you do not specify a name, SUBSET_1, is used by default.
AND|OR
By default, run cycles within a subset are in a logical OR relationship but you can change it to a logical AND, as long as the run cycle group result is a positive date or set of dates (Inclusive).
at time [timezone|tz tzname][+n day[s]]

Specifies a time dependency

time
Specifies a time of day. Possible values can range from 0000 to 2359.
tzname
Specifies the time zone to be used when computing the start time. See Managing time zones for time zone names. The default is the time zone of the workstation on which the job or job stream is launched.
Note: If an at time and an until or deadline time are specified, the time zones must be the same.
n
Specifies an offset in days from the scheduled start date and time.
schedtime time [timezone|tz tzname][+n day[s]]
Represents the time when the job stream is positioned in the plan.
time
Specifies a time of day in the format: HHHHmm. Possible values are from 0000 to 320000.
tzname
Specifies the time zone to be used when calculating the start time. See Managing time zones for time zone names. The default is the time zone of the workstation on which the job or job stream is launched.
n
Specifies an offset in days from the scheduled start date and time.
until time [timezone|tz tzname][+n day[s]] [onuntil action]

Depending on the object definition the until keyword belongs to, specifies the latest time a job stream must be completed or the latest time a job can be launched. It is mutually exclusive with the jsuntil keyword.

time
Specifies the time of day. The possible values are 0000 through 2359.
tzname
Specifies the time zone to be used when computing the time. See Managing time zones for time zone names. The default is the time zone of the workstation on which the job or job stream is launched.
Note: If an until time and an at or deadline time are specified, the time zones must be the same.
n
Specifies an offset, in days, from the scheduled date and time.
onuntil action
Depending on the object definition the until keyword belongs to, specifies:
  • The action to be taken on a job whose until time has expired but the job has not yet started.
  • The action to be taken on a job stream whose until time has expired but the job stream is not yet completed in SUCC state.
The following are the possible values of the action parameter:
suppr
The job or job stream and any dependent job or job stream do not run. This is the default behavior.

Once the until time expired on a job stream, the status for the job stream is calculated following the usual rules; suppressed jobs are not considered in the calculation. In case the job stream contains at least one every job its status is HOLD.

When the until time expires for a job, the job moves to HOLD status or keeps any previous status which is a final status.

If the until time is passed together with the onuntil suppr and the carryforward options, the job stream is carry forwarded by JnextPlan only if the until date is equal to the date when JnextPlan runs. If the until and the JnextPlan run dates are not the same, the job stream is not carry forwarded.

cont
The job or job stream runs when all necessary conditions are met and a notification message is written to the log when the until time elapses.

If the until time is passed together with the onuntil cont and the carryforward options, the job stream is always carry forwarded by JnextPlan.

canc
A job or job stream is cancelled when the until time specified expires. When using onuntil canc on jobs, the cancel operation on the job is issued by the FTA on which the job runs. Any job or job stream that was dependent on the completion of a job or job stream that was cancelled, runs because the dependency no longer exists.

If the until time is passed together with the onuntil canc and the carryforward options, the job stream is not carry forwarded by JnextPlan because it is already canceled.

Note: When using onuntil canc at job stream level, define as owner of the job stream the workstation highest in the hierarchy of the scheduling environment, among all workstations that own jobs contained in the job stream.
[jsuntil time [+n day[s]]] [onuntilaction]
Defines the latest start time of a job stream. It also determines the behavior of the jobs in the job stream when the job stream is approaching its latest start time. This keyword is mutually exclusive with the until keyword. Use the jsuntil keyword to avoid your job stream being suppressed if it starts right before its latest start time and the duration of one or more jobs in it exceeds the latest start time. For example, if you have a job stream with jsuntil set to 1000, and one of the jobs starts running at 959 and its duration exceeds the latest start time, the job and its successors run as scheduled.
time
Specifies the time of day. The possible values are 0000 through 2359.
tzname
Specifies the time zone to be used when computing the time. See Managing time zones for time zone names. The default is the time zone of the workstation on which the job or job stream is launched.
n
Specifies an offset, in days, from the scheduled date and time.
onuntil action
Depending on the object definition the until keyword belongs to, specifies:
  • The action to be taken on a job whose until time has expired but the job has not yet started.
  • The action to be taken on a job stream whose until time has expired but the job stream is not yet completed in SUCC state.
The following are the possible values of the action parameter:
suppr
The job or job stream and any dependent job or job stream do not run. This is the default behavior.

Once the until time expired on a job stream, the status for the job stream is calculated following the usual rules; suppressed jobs are not considered in the calculation. In case the job stream contains at least one every job its status is HOLD.

When the until time expires for a job, the job moves to HOLD status or keeps any previous status which is a final status.

If the until time is passed together with the onuntil suppr and the carryforward options, the job stream is carry forwarded by JnextPlan only if the until date is equal to the date when JnextPlan runs. If the until and the JnextPlan run dates are not the same, the job stream is not carry forwarded.

cont
The job or job stream runs when all necessary conditions are met and a notification message is written to the log when the until time elapses.

If the until time is passed together with the onuntil cont and the carryforward options, the job stream is always carry forwarded by JnextPlan.

canc
A job or job stream is cancelled when the until time specified expires. When using onuntil canc on jobs, the cancel operation on the job is issued by the FTA on which the job runs. Any job or job stream that was dependent on the completion of a job or job stream that was cancelled, runs because the dependency no longer exists.

If the until time is passed together with the onuntil canc and the carryforward options, the job stream is not carry forwarded by JnextPlan because it is already canceled.

Note: When using onuntil canc at job stream level, define as owner of the job stream the workstation highest in the hierarchy of the scheduling environment, among all workstations that own jobs contained in the job stream.
every rate {everyendtime time[+n day[s]]}
Defines the repetition rate at which instances of the same job stream are run over a time interval. The job stream is launched repeatedly at the specified rate until the time specified in everyendtime.
rate
The repetition rate, expressed in hours and minutes (hhmm), at which the instances of the job stream are launched.
time
The end time, expressed in hours and minutes (hhmm) when the repetition interval stops. After this time no more instances of the job stream are run. Use of the everyendtime keyword is mandatory.
n
The number of days that the value of everyendtime can be extended. For example, if you specify:
everyendtime 1550 + 1
and the job stream is scheduled to start running today at 10:00, the end time that the job stream instances will stop being launched is tomorrow at 15:50.

Example

The following example defines a run cycle group named, RCG2, that contains one inclusive run cycle, RUN_CYCLE1, and two exclusive run cycles, RUN_CYCLE2, and RUN_CYCLE3. To determine the run schedule of the job stream associated to this run cycle group, the intersection of the two exclusive run cycles (the two exclusive run cycles have a logical AND relationship between them) is subtracted from the inclusive run cycle. The following are the characteristics of the run cycle group:
An inclusive run cycle RUN_CYCLE1
where,
  • The calendar, CAL1, defines days that should be considered non-working days for the job stream. Saturday and Sunday are declared working days.
  • The job stream runs not earlier than two days after March 31, 2008 (April 2), and not later than two days after April 12, 2008 ( April 14). Every day, the job stream is delayed by two days.
  • The job streams runs every day (after the two-day delay) beginning at 7 a.m. and it cannot start later than 9 a.m., otherwise, it is suppressed and does not run at all. The job stream should complete by 10 a.m.
An exclusive run cycle, RUN_CYCLE2
If the job stream falls on a non-working day, then the nearest workday before the non-working day is excluded.
If the job stream falls on April 1, 2008, and this day happens to be a non-working day, then the nearest workday after the non-working day is excluded.
An exclusive run cycle, RUN_CYCLE3
If the job stream falls on April 1, 2008, and this day happens to be a non-working day, then the nearest workday after the non-working day is excluded.
RUNCYCLEGROUP RCG2
DESCRIPTION "Sample RunCycle Group"
VARTABLE TABLE1
FREEDAYS CAL1 -SA -SU
  ON     RUNCYCLE RUN_CYCLE1 VALIDFROM 03/31/2008 VALIDTO 04/12/2008 DESCRIPTION
         "Inclusive Run Cycle" VARTABLE TABLE1 "FREQ=DAILY;" FDIGNORE
         (AT 0700 +2 DAYS UNTIL 0900 +2 DAYS ONUNTIL SUPPR DEADLINE 1000 +2 DAYS)

  EXCEPT RUNCYCLE RUN_CYCLE2 VALIDFROM 03/31/2008 VALIDTO 04/12/2008 DESCRIPTION
         "Exclusive Run Cycle" CAL1 FDPREV SUBSET SUBSET_A AND
         (AT 0700 +2 DAYS)

  EXCEPT RUNCYCLE RUN_CYCLE3 VALIDFROM 03/31/2008 VALIDTO 04/12/2008 DESCRIPTION 
         "Exclusive Run Cycle" 04/01/2008 FDNEXT SUBSET SUBSET_A AND
         (SCHEDTIME 0700 +2 DAYS)
SCHEDTIME 0700 TZ Europe/Berlin +2 DAYS UNTIL 0900 TZ Europe/Berlin +2 DAYS ONUNTIL
          CONT DEADLINE 1000 TZ Europe/Berlin +2 DAYS
END

See also

From the Dynamic Workload Console you can perform the same task as described in:

Creating and managing run cycle groups and their run cycles.