Run cycle group definition

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]
       [description ”text”]
       [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]
          [description ”text”]
          {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.

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.