Calendars

A calendar is a set of scheduling criteria that you can apply to multiple jobs, instead of having to define scheduling criteria in each individual job.

The following sections provide details about the available types of calendars that you can define and the parameters that you use in calendar definitions

Calendar:Regular

The following example shows how to define a regular calendar. Such calendars are based on certain dates (the days of the month and/or the days of the week) in a selected year:

Copy
{
   "RegularCalendar": {
      "Type" :  "Calendar:Regular",
      "Description" : "My regular calendar",
      "Server" : "serverName",
      "Alias" : "ZOS_NAME",
      "When": {
        "Years": [{
           "Year": "2020",
           "JAN" : ["10-15","22","24"],
           "APR" : ["1","12-22"]
        },{
           "Year": "2021",
           "FEB" : ["5-10","22","24"],
           "APR" : ["4","12-18"],
           "JUN" : ["2"]
        }]
      }
   }
}

The following tables describes the Calendar:Regular command parameters.

Parameter

Description

Description

(Optional) A textual description for the calendar.

Server

Name of Control-M/Server, or Global (for ALL servers, the default).

Alias

Calendar name for z/OS jobs.

When

Scheduling definitions for when to run jobs.

Definitions are grouped by year under the Years object. Each year has the following parameters:

  • Year: 4-digit calendar year (YYYY format).

  • Months and Dates: A separate parameter for each month in which you want to define dates. All these parameters are optional.

    The parameter name is the first 3 letters of the name of the month.

    The parameter value is a combination of individual days and/or ranges of days.

Calendar:Periodic

Periodic calendars are used to divide the year into a combination of working periods that you define (for example, 13 periods of varying lengths instead of 12 months). The following example shows how to define a periodic calendar:

Copy
{
    "PeriodCalendar": {
       "Type": "Calendar:Periodic",
       "Description": "My periodic calendar",
       "Server": "serverName",
       "Alias" : "ZOS_NAME",
       "When": {
           "Periods": [{
               "Period": "A",
               "Years": [{
                  "Year": "2020",
                  "JAN": ["2", "5-7"],
                  "FEB": ["3", "6-8"]
               },{
                  "Year": "2021",
                  "JAN" : ["4","7-9"],
                  "APR" : ["5","8-10"]
               }]
             },{
               "Period": "B",
               "Years": [{
                  "Year": "2020",
                  "JAN": ["3", "8-10"],
                  "MAR": ["3", "6-8"]
               },{
                  "Year": "2021",
                  "JAN" : ["4","7-9"],
                  "MAY" : ["5","8-10"]
               }]
             },{
               "Period": "All",
               "Years": [{
                 "Year": "2020",
                 "JAN" : ["20-21","31"]
               },{
                 "Year": "2021",
                 "JAN" : ["19-20","30"]
               }]
           }]
        }        
    }   
}

The following tables describes the Calendar:Periodic command parameters.

Parameter

Description

Description

(Optional) A textual description for the calendar.

Server

Name of Control-M/Server, or Global (for ALL servers, the default).

Alias

Calendar name for z/OS jobs.

When

Scheduling definitions for when to run jobs.

Definitions are grouped by period under the Periods object.

Each period is identified by its Period parameter, a one-letter period ID. Valid values are from A to Z, excluding N and Y.

For scheduling definitions that are applied to ALL periods, you can define an additional period with a Period parameter value of All.

Further definitions of a period are grouped by year under the Years object. Each year has the following parameters:

  • Year: 4-digit calendar year (YYYY format).

  • Months and Dates: A separate parameter for each month in which you want to define dates. All these parameters are optional.

    The parameter name is the first 3 letters of the name of the month.

    The parameter value is a combination of individual days and/or ranges of days.

Scheduled dates must not overlap between periods.

Calendar:RuleBasedCalendar

The following example shows how to define a rule-based calendar (RBC). Such calendars are based on flexible rules that you define, independent of specific years or specific months:

Copy
{
    "RuleBasedCalendar": {
        "Type": "Calendar:RuleBasedCalendar",
        "Server": "serverName",
        "Alias" : "ZOS_NAME",
        "When": {
            "Schedule": "Everyday",
            "MonthDays":["1","+2","-3",">4","<5","D6","L7"],
            "MonthDaysCalendar": "Summer2020",
            "Months": ["JAN", "OCT", "DEC"],
            "WeekDays" : ["SUN","+MON","-TUE",">WED","<THU"],
            "WeekDaysCalendar" : "Summer2020",
            "DaysRelation" : "OR",
            "StartDate":"20200322",
            "EndDate":"20200325",
            "ActivePeriod" :false,
            "DaysKeepActive": "0",
            "ConfirmationCalendars": {
                "Calendar": "Holidays",
                "ExceptionPolicy": "OrderOnNextConfirmedDay",
                "ShiftBy": "1"
            }
        }
    }
}

The following tables describes the Calendar:RuleBasedCalendar command parameters.

Parameter

Description

Description

(Optional) A textual description for the calendar.

Server

Name of Control-M/Server, or Global (for ALL servers, the default).

Alias

Calendar name for z/OS jobs.

When

Scheduling parameters that set the rules for when to run jobs. See next table.

Under the When object, you can set combinations of the following properties:

Property

Description

Schedule

One of the following options:

  • "Everyday": Scheduling is applied every day, provided that the running criteria are met.

  • "Never": No scheduling is defined, and the job must be ordered manually.

MonthDays

One or more days in the range of 1 to 31.

For all days of the month, use "ALL" (the default value).

If you combine the MonthDays property with the MonthDaysCalendar property, you can create advanced rules, using the following syntax:

  • 1: Day 1 included only if defined in the calendar.

  • +2: Day 2 included regardless of calendar.

  • -3: Day 3 excluded regardless of calendar.

  • >4: Day 4 or next closest calendar working day.

  • <5: Day 5 or previous closest calendar working day.

  • D6 or -D6: The 6th calendar working day since the beginning of the month, to be included or excluded (respectively).

  • L7 or -L7: The 7th from the last calendar working day of the month, to be included or excluded (respectively).

  • D6PA or D6P*: If MonthDaysCalendar is of type periodical, you can use PA or P* to specify a calendar period name such as A,B,C, or you can use * for any period.

    This can be added to both D and L, and to both an include or an exclude.

MonthDaysCalendar

The name of a previously defined calendar from which to derive the days of the month.

Months

One or more of the following:

"JAN", "FEB", "MAR", "APR","MAY","JUN", "JUL", "AUG",

"SEP", "OCT", "NOV", "DEC".

For all months of the year, use "ALL" (the default value).

WeekDays

One or more of the following:

"SUN","MON","TUE","WED","THU","FRI","SAT".

For all days of the week, use "ALL" (the default value).

In addition, you can specify a specific day in a specific week of the month using a value with the following format: DdayWn.

For example, DMONW2 means Monday of the 2nd week of the month. Valid values for n are 1-6.

If you combine the WeekDays property with the WeekDaysCalendar property, you can create advanced rules, using the following syntax:

  • SUN: Sunday included only if defined in the calendar.

  • +MON: Monday included regardless of calendar.

  • -TUE: Tuesday excluded regardless of calendar.

  • >WED: Wednesday or next closest calendar working day.

  • <THU: Thursday or previous closest calendar working day.

  • D6 or -D6: The 6th calendar working day of the week (with a number in the range of 0-6), to be included or excluded (respectively).

  • L3 or -L3: The 3rd from the last calendar working day of the week (with a number in the range of 0-6), to be included or excluded (respectively).

  • D6PA or D6P*: If WeekDaysCalendar is of type periodical, you can use PA or P* to specify a calendar period name such as A,B,C, or you can use * for any period.

    This can be added to both D and L, and to both an include or an exclude.

WeekDaysCalendar

The name of a previously defined calendar from which to derive the days of the week

DaysRelation

The logical relationship between MonthDays and WeekDays:

  • AND: For jobs to run, both WeekDays and MonthDays contraints must be met. The default.

  • OR: Jobs will run when either WeekDays constraints are met or MonthDays constraints are met.

SpecificDates

Specific dates for running jobs.

For each date, use the format "MM/DD" (enclosed in quotes). Separate multiple dates with commas.

Note: The SpecificDates option cannot be used in combination with options WeekDays, Months, or MonthDays.

However, since the default for these options is "ALL", you must specify these options with a value of "NONE".

StartDate

Start date, in YYYYMMDD format, for a period when the job can/cannot run. Used with EndDate.

EndDate

End date, in YYYYMMDD format, for a period when the job can/cannot run. Used with StartDate.

ActivePeriod

Whether the defined period (as defined by StartDate and EndDate) is a period of activity or inactivity, with the following values:

  • True: Period of activity, when the job CAN run. The default.

  • False: Period of inactivity, when the job CANNOT run.

DaysKeepActive

The number of days to keep jobs that did not run at the scheduled date.

Valid values: 0-99

0: Jobs are never kept.

99: Jobs are kept forever.

ConfirmationCalendars

Details of a Confirmation calendar to use for validation of scheduling dates, including an indication of how to handle jobs that are scheduled for a non-working day in this calendar.

   Calendar

The name of the predefined Confirmation calendar, in which work days are indicated

   ExceptionPolicy

A policy to follow when a job is scheduled on a non-working day. Choose from one of the following options:

  • DoNotOrder

  • OrderOnNextConfirmedDay

  • OrderOnPreviousConfirmedDay

  • OrderAnyway

Default: DoNotOrder

   ShiftBy

The number of additional confirmed days to move the job, beyond the action specified by the exception policy. Specify one of the following:

  • A positive number of additional days to move forward when the exception policy is OrderOnNextConfirmedDay.

  • A negative number of additional days to move backward when the exception policy is OrderOnPreviousConfirmedDay.

Default: 0