defcal

This utility has been deprecated. It is no longer enhanced and support will be discontinued in version 9.0.22. For more information, see emdef Utility Suite Deprecation.

The defcal utility imports a calendar definition into the Control-M/EM database.

defcal reads calendar definitions directly from a plain text input file (in XML format) instead of reading them from the command line.

The defcal utility validates the XML rule file according to the validation process in Control-M/EM version 9.0.19 and above.

By default, the utility validates the XML file in accordance with the EmdefValidationVersion system parameter in the CCM. F You can change the value in the CCM without the need to add the switch to the command, which may be preferable if you have many scripts that use a particular validation version.

For an example of the two validation processes see emdef Validation Service Error Message Example.

Importing a Calendar Using the defcal Utility

This procedure describes how to import a calendar definition into the Control-M/EM database using the defcal utility.

Begin

  1. Do one of the following:

    • UNIX: Log in to a Control-M/EM account.

    • Windows: Open a command prompt window. You do not need to be in the Control-M/EM database directory.

      For Windows client installations, open a command prompt window and navigate to the <EM Instance Name>\bin directory.

  2. Enter either of the following commands:

    • emdef defcal [-USERNAME <user> [-PASSWORD <password>] | -PASSWORD_FILE <password file>] -HOST <GUI Server Name> -SRC_FILE <XML File name> [-vv 2]

    • emdef defcal [-u <user> [-p <password>] | -pf <password file>] -s <GUI Server Name> -src <XML file name> [-vv 2]

      For Windows, you do not need to use the emdef prefix.

For more details on the defcal parameters and options, see emdef General Parameters and emdef Switches.

The defcal input file is checked and processed. If there are any errors in the file, a message is displayed specifying the lines with the errors.

defcal XML File Rules

The calendars that you create for use with the defcal utility are written in XML format and saved in a text file. When this file is invoked, its contents are passed to the Control-M/EM database.

Instructions for creating an XML format input file are in XML File Rules.

The following rules apply to the defcal utility input file:

  • More than one calendar can be specified in a defcal file.

  • The XML file is case-sensitive.

  • The definition for a single calendar can cover a period of one or more years.

  • All parameter values (such as strings or digits) must be enclosed in quotation marks

    JOBNAME="Job1"

defcal XML File Parameters

The following table lists the defcal utility input file parameters:

Parameter

Description

The first two lines of the XML request file for this API request contain information that specifies the version of XML, the text encoding format being used, and the location of the .dtd file.
DEFCAL

Indicates to Control-M/EM database that the defcal utility is initiated. Calendar definitions are placed between the opening and closing DEFCAL tags. One or more calendars can be specified.
CALENDAR

Indicates the opening and closing tags of a single calendar definition. The parameters of the job are listed between the tags.

<CALENDAR DATACENTER="EM5A" NAME="AcctJob1" TYPE="Relative"></CALENDAR>

DATACENTER: Name of the Control‑M installation that the calendar definition belongs to.

NAME: Name of the calendar.

TYPE: Calendar type.

Valid values:

  • Regular

  • Periodic

  • Relative

YEAR

Determines the year-specific definitions in the calendar.

YEAR NAME="2021"

DAYS="YYYYYYYYYYYYYYYYYYNYYYYYYYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNNYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY YYYNNYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYNYYYYYYYYYYYYYYY YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNNYY YYYYYYYYYYYYYYYYYYY"

DESCRIPTION="This is the Accounting Jobs calendar for 2021."

NAME: Year for which the calendar definition applies.

The year during which the calendar is active. Only one year can be entered for this attribute, but more than one YEAR parameters can be included in a calendar definition.

The value of this attribute is expressed as YYYY (for example, 2021).

DAYS: Days that the job is ordered.

Valid values:

  • For a Relative calendar:

    • Y

    • N

    • +

    • -

  • For a Regular calendar:

    • Y

    • N

  • For a Periodic calendar:

    any character other than Y, N, +, or -.

Each Y and N represents a single day of the year. The value of the DAYS parameter is 365 characters long (366 for a leap year). The first letter of the DAYS value is January first. The last letter is December 31.

DESCRIPTION: Text description of the calendar. For Regular and periodic calendars only.
RULE_BASED_CALENDAR

Indicates the opening and closing tags of a single Rule-Based Calendar definition. The parameters of the job are listed between the tags.

<RULE_BASED_CALENDAR DATACENTER="EM5A" NAME="AcctJob1"></RULE_BASED_CALENDAR>

  • DATACENTER: Name of the Control‑M installation that the calendar definition belongs to.

  • NAME: Name of the calendar.

  • DAYS: Days of the month on which the job is ordered.

  • DAYS_AND_OR: Indicates the relationship between specified Days values and Weekdays values.

    Valid values:

    • OR

    • AND

      Default: OR

  • WEEKDAYS: Days of the week on which to order the job.

    Valid values:

    • 0 - 6

    • ALL

    • blank

  • DATE: Specific dates on which to order the job. String. MMDD format. Optional.

  • DAYSCAL: Name of a user-defined calendar used to specify a set of days. String. Optional.

  • WEEKSCAL: Name of a calendar to be used to validate specified weekdays on which to order the job. String. Optional.

  • CONFCAL: Specifies a calendar that is used to validate all specified days and dates on which to schedule the job. String.

  • SHIFT: Sub-parameter of CONFCAL. Describes how to shift the scheduling date of the job.

    Valid values:

    • IGNOREJOB

    • PREVDAY

    • NEXTDAY

    • NOCONFCAL

  • SHIFTNUM: Sub-parameter of CONFCAL. Number of days to shift the scheduling date of the job.

    Default: +00

  • MAXWAIT: Number of extra days (beyond the original scheduling date) that the job is allowed to remain in the Active Jobs database awaiting execution. Integer. Default: 00

    JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC: Months when the job can run. Not including a month is the same as including a month having the value 0.

    Valid values:

    • 0

    • 1

      Default: 0

  • ACTIVE_FROM: Starting date of the Rule-Based Calendar. Format: YYYYMMDD

  • ACTIVE_TILL: Ending date of the Rule-Based Calendar. Format: YYYYMMDD

Import a Regular Calendar XML File Example

In the defcal XML file, a regular calendar, AcctCal3, is imported into the EM5NY data center.

Copy 
<DEFCAL>
<CALENDAR
DATACENTER="EM5NY"
NAME="AcctCal3"
TYPE="Regular">
<YEAR
NAME="2016"
DAYS="YYYYYYYYYYYYYYYYYYNYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNNYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYNYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNN
NYYYYYYYYYYYYYYYYYYYYY"
DESCRIPTION="Calendar for 2016."/>
</CALENDAR>
</DEFCAL>

Import Two Calendars into Different Data Centers XML File Example

Two calendars are imported, each into a different data center, with a single defcal XML file.

Copy 
<DEFCAL>
<CALENDAR
DATACENTER="EM5NY"
NAME="AcctCal3"
TYPE="Regular">
<YEAR
NAME="2016"
DAYS="YYYYYYYYYYYYYYYYYYNYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNNYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYNYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNN
NYYYYYYYYYYYYYYYYYYYYY"
DESCRIPTION="Calendar for 2016."/>
<CALENDAR
DATACENTER="EM2LA"
NAME="HRCal3"
TYPE="Regular">
<YEAR
NAME="2016"
DAYS="YYYYYYYYYYYYYYYYNNNYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNNNNYYYYYYYYYYYYYYYYNNNYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNNYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYNYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYNN
NYYYYYYYYYYYYYYYYYYNNN"
DESCRIPTION="Calendar for 2016."/>
</CALENDAR>
</DEFCAL>