Run cycle group definition

A run cycle group is a database object within which one or more run cycles are 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.

When creating a scheduling object, you can define it in a folder. If no folder path is specified, then the object definition is created in the current folder. By default, the current folder is the root (\) folder, but you can customize it to a different folder path. You can also use the composer rename command to move and rename objects in batch mode that use a naming convention to a different folder using part of the object name to assign a name to the object.

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

Syntax

runcyclegroup
[folder/]runcyclegroupname [description“text”]
     vartable [folder/]tablename
       [freedays [folder/]calendarname [-sa] [-su]]
[on [runcycle [folder/]name
       [validfrom date] [validto date]
       [description ”text”]
       [vartable [folder/]table_name]]
      {date|day|[folder/]calendar|request|”icalendar”|runcyclegroup} [,...]
       [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 [folder/]name]
          [validfrom date] [validto date]
          [description ”text”]
          {date|day|[folder/]calendar|request|”icalendar”|runcyclegroup} [,...]
          [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

[folder/]runcyclegroupname

Specifies the name of the run cycle group, optionally preceded by the folder name within which the run cycle group is defined. The run cycle group name can contain up to eight alphanumeric characters, including dashes (-) and underscores (_), and must start with a letter.

description “text”

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 [folder/]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 [folder/]Calendar_Name [-sa] [-su]]

Specifies a freeday calendar for calculating workdays for the job stream. It can also set Saturdays and Sundays as workdays.

[folder/]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 2018 and on the 12th of June 2018 the value is:

on
20180525,20180612

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

[folder/]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.

runcyclegroup

Specified one or more run cycles that combined together produce a set of run dates for a job stream. The run cycle group must be expressed using the following syntax: $RCG runcyclegroupname.

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 240000, or 0000 + <number of days>.
Where <number of days> can be from 1 to 100 days.
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.

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

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

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.

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, 2018 (April 2), and not later than two days after April 12, 2018 ( 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, 2018, 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, 2018, 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/2018 VALIDTO 04/12/2018 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/2018 VALIDTO 04/12/2018 DESCRIPTION
         "Exclusive Run Cycle" CAL1 FDPREV SUBSET SUBSET_A AND
         (AT 0700 +2 DAYS)

  EXCEPT RUNCYCLE RUN_CYCLE3 VALIDFROM 03/31/2018 VALIDTO 04/12/2018 DESCRIPTION 
         "Exclusive Run Cycle" 04/01/2018 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

Run cycle group definition

Syntax

Arguments

Example

See also