Calendars

Control-M calendars are user-defined timetables, which enable you to apply scheduling limitations to one or more job and SMART folder definitions. This eliminates the need to manually define scheduling definitions for every job and SMART folder in your Workspace.

You can define the following types of calendars:

Regular Calendar: A schedule of specific dates that you define, such as certain days of the month or week in a defined year, as described in Calendar:Regular.
Periodic Calendar: A schedule of different calendar periods other than months and days, as described in Calendar:Periodic.
Rule-Based Calendar: A schedule defined by specific rules, as described in Calendar:RuleBasedCalendar.

Calendar:Regular

This following example shows how to define a Regular calendar, which schedules jobs to run on specific month days and weekdays 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 parameters.

Parameter	Description
Description	(Optional) Defines a textual description of the calendar.
Server	Defines the name of a Control-M/Server, or Global (for ALL servers, the default).
Alias	Defines the calendar name for z/OS jobs.
When	Defines the scheduling definitions. Months and dates are grouped by year under the Years object, as follows: Year: Defines a 4-digit calendar year, in YYYY format. Months and Dates: (Optional) Defines a separate parameter for each month where you want to define dates, as follows: Name: Defines the month with the first three letters of that month, such as "APR". Value: Defines the days or range of days in a month, or both, such as "4", "12-18".

Calendar:Periodic

Periodic calendars schedule jobs to run over periods that can span weeks, months, or years, such as the division of a year into four quarters. You can define nonconsecutive periods of varying lengths of time. However, you cannot define a period that exceeds 255 days or that is broken up by more than 33 days.

You can create a period that is more than one year. For example, Period A can include November 2019 through February 2020. Scheduling a job via Periodic calendars, enables you to select the periods that the job runs in, and then add additional scheduling criteria.

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 parameters.

Parameter	Description
Description	(Optional) Defines a textual description of the calendar.
Server	Defines the name of a Control-M/Server, or Global (for ALL servers, the default).
Alias	Defines the calendar name for z/OS jobs.
When	Defines the scheduling definitions, which are grouped as follows: Periods: All periods are grouped and defined in the Periods object. Period: Each period is defined by the Period parameter, which is a one-letter period ID that can be any value from A–Z, except for N and Y. To apply scheduling definitions to all periods, you can define an additional period as follows: Name: Period Value: All Years: All years, months, and days are grouped and defined in the Years object. Year: Each year is defined by the Year object, which is a 4-digit calendar year, in YYYY format. Months and Days: (Optional) Months and days are grouped by year under the Years object, and are defined as follows: Name: Defines the name of the month, in MMM format, where MMM is first three letters of that month, such as "APR". Value: Defines the days or range of days in a month, or both, such as "4", "12-18". Scheduled dates must not overlap between periods.

Calendar:RuleBasedCalendar

A Rule-Based calendar (RBC) is a user-defined calendar that enables you to define and apply a schedule of working days The dates selected in a Regular, Periodic, or Rule-Based calendar. to SMART folders, sub-folders, and jobs. RBCs enable you to define schedules with values that cannot be specified as absolute values, such as specific days or dates, and requires more complex scheduling criteria.

You can define the following types of RBCs:

Specific Dates: Defines scheduling criteria based specific dates, independent of a calendar year, for up to 12 months.
Week Days: Defines scheduling criteria based on specific weekdays, or on specific weekdays in specific weeks, which can also be based on a calendar.
Month Days: Defines scheduling criteria based on specific month days, which can also be based on a calendar.
Advanced: Defines scheduling criteria based on a combination of scheduling options that includes months, weekdays, and days of the month.

The following example shows how to define a Rule-Based calendar (RBC):

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 parameters.

Parameter	Description
Description	(Optional) Defines a textual description of the calendar.
Server	Defines the name of a Control-M/Server, or Global (for ALL servers, the default).
Alias	Defines the calendar name for z/OS jobs.
When	Defines the scheduling definitions, which are grouped under this object.
Schedule	Determines one of the following scheduling options: "Everyday": Applies the scheduling criteria daily, provided that the run criteria are met. "Never": Does not the apply scheduling criteria. The job must be run manually.
MonthDays	Defines one or more days of the month. Each day must be separated with a , and written in the following format: ALL: Defines all the days of the month. n: Defines a day of the month. where n is any day between 1 and 31. To define advanced rules, you can combine the MonthDays and MonthDaysCalendar parameters, as follows: +n: Includes day n. where n is any day between 1 and 31. -n: Excludes day n. >n: Defines day n or the next closest working day The dates selected in a Regular, Periodic, or Rule-Based calendar.. <n: Defines day n or the previous closest working day. Dn: Includes the n^th working day, counting from the beginning of the month. -Dn: Excludes the n^th working day, counting from the beginning of the month. Ln: Includes the the n^th working day, counting from the end of the month. -Ln: Excludes the the n^th working day, counting from the end of the month. nPx: If MonthDaysCalendar is periodical, determines one or more calendar periods. where x is a calendar period name, such as A or B, or the wildcard . You can include a D or L in front of this value to include or exclude a day. Default: ALL 1: Includes Day 1 only if it is defined in the calendar. +2: Includes Day 2, regardless of the calendar. -3: Excludes Day 3, regardless of calendar. >4: Defines Day 4 or the next closest working day The dates selected in a Regular, Periodic, or Rule-Based calendar.. <5: Defines Day 5 or the previous closest working day. D6 or -D6: Defines the 6^th working day from the beginning of the month, to be included or excluded (respectively). L7 or -L7: Defines the 7^th from the last working day of the month, to be included or excluded (respectively). D6PA*: Includes working day 6 of calendar period A.
MonthDaysCalendar	The name of a previously defined calendar from which to derive the days of the month.
Months	Defines one or more months, as follows: "JAN", "FEB", "MAR", "APR","MAY","JUN", "JUL", "AUG","SEP", "OCT", "NOV", "DEC" To define all calendar months, type "ALL" (Default).
WeekDays	Defines one or more days, as follows: "SUN","MON","TUE","WED","THU","FRI","SAT" To define all weekdays, type "ALL" (Default). You can also type a specific weekday in a specific month, in the following format: DdayWn. DMONW2 indicates the 2^nd Monday of the month. Valid values for n are 1–6. You can combine the WeekDays property with the WeekDaysCalendar property to create advanced rules, as follows: 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 6^th 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 3^rd 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 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	Defines the name of a previously defined calendar that the days of the week are derived from.
DaysRelation	Determines the logical relationship between MonthDays and WeekDays, as follows: AND: For jobs to run, both WeekDays and MonthDays contraints must be met. OR: Jobs will run when either WeekDays constraints are met or MonthDays constraints are met. Default: AND
SpecificDates	Specific dates for running jobs. For each date, use the format "MM/DD" (enclosed in quotes). Separate multiple dates with commas. SpecificDates cannot be used in combination with 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 or cannot run. Used with EndDate.
EndDate	End date, in YYYYMMDD format, for a period when the job can or cannot run. Used with StartDate. If the EndDate is before the StartDate and the ActivePeriod parameter is set to True (the default), the difference between the two dates is treated as an absolute value for the period when the job can run.
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. False: Period of inactivity, when the job CANNOT run. Default: True
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	Determines a predefined Regular or Periodic calendar that Control-M compares with the RBC. This is also known as the confirmation calendar.
ExceptionPolicy	Determines one of following scheduling changes to apply when a job is scheduled to run on a non-working day in the confirmation calendar. DoNotOrder: Prevents the job from running. OrderOnNextConfirmedDay: Runs the job on the next working day in the confirmation calendar. OrderOnPreviousConfirmedDay: Runs the job on the previous working day in the confirmation calendar. OrderAnyway: Runs the job on the currently scheduled working day. ShiftAndDoNotRun: Shifts the job run by the number of days defined in the Shift By parameter, and then prevents the job from running if it is not a working day in the confirmation calendar. ShiftAndRunOnNextConfirmedDay: Shifts the job run by the number of days defined in the Shift By parameter, and then runs the job on the following working day in the confirmation calendar. ShiftAndRunOnPreviousConfirmedDay: Shifts the job run by the number of days defined in the Shift By parameter, and then runs the job on the previous working day in the confirmation calendar. ShiftAndRunAnyway: Shifts the job run by the number of days defined in the Shift By parameter, and then runs the job. Default: DoNotOrder
ShiftBy	Determines the number of days to shift all scheduled job runs. Valid Values: 0: Does not shift the scheduled job runs by any number of days. 1 to 62: Shifts all scheduled job runs forward by 1–62 days. -1 to -62: Shifts all scheduled job runs backward by 1–62 days.