on

This is a job stream keyword that defines when and how often a job stream is selected to run. If omitted the job stream is not added to the preproduction plan. The on keyword must follow the schedule keyword. See except for more information.

Syntax

on [runcycle name

[valid from date] [valid to date]

[descriptiontext”]

[vartable table_name]]

{date|day|[folder/]calendar|request|”icalendar|runcyclegroup} [,...]

[fdignore|fdnext|fdprev][subset subsetname AND|OR]

Arguments

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 2023 and on the 12th of June 2023 the value is:
on
20230525,20230612
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).

Comments

You can define multiple instances of the on keyword for the same job stream. Multiple on instances must be consecutive within the job stream definition. Each instance is equivalent to a run cycle to which you can associate a freeday rule.

Each instance of the keyword can contain any of the values allowed by the on syntax.

If the run cycle and job stream start times are both defined, the run cycle start time takes precedence when the job stream is scheduled with JNextPlan. When the job stream is launched with the submit command, the run cycle start time is not used.

Examples

The following example selects job stream sked1 on Mondays and Wednesdays:
schedule sked1 on mo,we
The following example selects job stream sked3 on June 15, 2023, and on the dates listed in the apdates calendar:
schedule sked3 on 6/15/23,apdates
The following example selects job stream sked4 two weekdays before each date appearing in the monthend calendar:
schedule sked4 on monthend -2 weekdays
The following example selects job stream testskd1 every weekday except on Wednesdays:
schedule testskd1 on weekdays
  except we 
The following example selects job stream testskd3 every weekday except May 15, 2023 and May 24, 2023:
schedule testskd3 on weekdays
  except 05/16/2023,05/24/2023 
The following example selects job stream testskd4 every day except two weekdays prior to any date appearing in a calendar named monthend:
schedule testskd4 on everyday
  except monthend -2 weekdays 
Select job stream sked1 to run all Mondays, Fridays, and on 29/12/2023. If Mondays and 29/12/2023 are non-working days, run the job stream on the nearest following workday. If Fridays are non-working days, run the job stream on the nearest preceding day. In this example, the non-working days are Saturdays, Sundays, and all the dates listed in the default HOLIDAYS calendar. Workdays are all days from Monday to Friday if they are not listed in the HOLIDAYS calendar.
schedule sked1
on mo, 12/29/2023 fdnext
on fr fdprev
This example shows the output of the display command of job stream testcli defined to run on different run cycles on workstation site2:
display js=site2#testcli
obtained in 120-column format by setting MAESTROCOLUMNS=120 before accessing the composer command-line:
JobstreamName Workstation Draft Valid From  Valid To UpdatedBy UpdatedOn  LockedBy
------------- ----------- ----- -------–-  ------- --------- ---------  --------
TESTCLI       SITE2       Y     08/25/2023 -       mdmDBE4   08/25/2023 mdmDBE4

SCHEDULE W5#TESTCLI VALID FROM 08/25/2023 TIMEZONE ACT
DESCRIPTION "Job stream with several run cycle settings."
DRAFT
ON RUNCYCLE M5 VALID FROM 08/25/2023 
   DESCRIPTION "monthly" 
   "FREQ=MONTHLY;INTERVAL=5;BYMONTHDAY=-3,1" 
   ( AT 0000 )
ON RUNCYCLE W4 VALID FROM 08/25/2023 
   DESCRIPTION "weekly" 
   "FREQ=WEEKLY;INTERVAL=5;BYDAY=MO,WE" 
   FDNEXT ( AT 0000 )
ON RUNCYCLE D3 VALID FROM 08/25/2023 
   DESCRIPTION "daily" 
   "FREQ=DAILY;INTERVAL=2" 
   FDPREV ( AT 0000 )
ON RUNCYCLE C2 VALID FROM 08/25/2023 
   DESCRIPTION "calendar" 
   ITALY +2 DAYS 
   ( AT 0000 )
ON RUNCYCLE M6 VALID FROM 08/25/2023 
   DESCRIPTION "monthly" 
   "FREQ=MONTHLY;INTERVAL=2;BYDAY=1MO,1TH,2WE" 
   ( AT 0000 +2 DAYS )
ON RUNCYCLE Y7 VALID FROM 08/25/2023 
   DESCRIPTION "yearly" 
   "FREQ=YEARLY;INTERVAL=7" 
   ( AT 0100 )
ON RUNCYCLE SS1 VALID FROM 08/25/2023   
   08/10/2023,08/18/2023,08/20/2023,08/25/2023 
   ( AT 0000 UNTIL 0000 +1 DAYS ONUNTIL SUPPR DEADLINE 0000 +2 DAYS )
EXCEPT RUNCYCLE S1 VALID FROM 08/25/2023 
   DESCRIPTION "simple"   
   08/26/2023,08/28/2023,08/30/2023,09/13/2023 
   ( AT 0000 )

CARRYFORWARD
MATCHING SAMEDAY
FOLLOWS LAB235004#SROBY2.@
FOLLOWS X8#COPYOFJS2.RR
FOLLOWS XA15::TPA
KEYSCHED
LIMIT 22
PRIORITY 15
:
X8#PIPPO AS JOBTC
 CONFIRMED
 PRIORITY 13
 KEYJOB
 FOLLOWS W5#POPO.@
 FOLLOWS X8#JS2.F3
END

AWSBIA291I Total objects: 1
The calendar ITALY is a custom calendar defined in the database that sets the workdays and holidays of the calendar in use in Italy.