The emdef is a command line utility used to make various modifications to calendar definitions in the Control-M/EM database. It can be used to extract data as a backup, or for migration from one to another environment.

The emdef need some parameters which vary according to the method to be executed, methods related calendars are:

  • copydefcal: Creates a new calendar definition identical to an existing one
  • exportdefcal: Exports calendar definitions to a file for use as input to other utilities
  • defcal: Imports calendar definitions from a file

At a customer this tool is widely used to automate some daily actions, e.g. export calendars and integrate them in other environment.

Basic parameters definition

To run emdef there are some fixed parameters whatever the method used, the syntax should be like:

emdef <METHOD_TO_USE> [-USERNAME <userName> [-PASSWORD <password>] | -PASSWORD_FILE <passwordFile>] -HOST <guiServerName> ...
  • userName: The Control-M/EM user name
  • password: The control-M/EM user password
  • passwordFile: Here you have the choice to put the user and password in the command line, or use the passwordFile which is a file containing an unencrypted user name and password on separate lines in the below format:
    user=userName
    password=password

    I personally recommend this practice to avoid adding user/password in the command line, on the other hand you have to correctly set file permissions!

  • guiServerName: Control-M/EM GUI server host name or IP address

Let’s move to methods to better understand this utility.

Methods definition

copydefcal

The copydefcal method creates new calendar(s) definition in the Control-M/EM database identical to existing calendar(s) definition. Calendar(s) can be copied and saved under different names in the same data center, or can be copied to a different data center and saved under the same or different names.
As you noticed one or multiple calendars can be handled in the same time using the * wildcard character.

To run the copydefcal utility, you need to specify basic parameters shown before plus the below one:

-arg <argFileName>

=> Path and name of the arguments file containing the copydefcal specifications

Example: Copy all calendars from one datacenter to another

  1. Create an argument file copycal.xml like the following:
    <COPYCAL>
      <DATACENTER FROM="DC_A" TO="DC_B"/>
      <CALENDAR FROM="*" TO="*"/>
    </COPYCAL>
    
  2. Create password file credentials.txt:
    user=emuser
    password=MyEmUserPass
    
  3. Execute the command:
    emdef copydefcal -pf <passwordFile> -s <guiServerName> -arg <argFileName>

    Which correspond to:

    emdef copydefcal -pf credentials.txt -s guiserverhostname -arg copycal.xml

exportdefcal

The exportdefcal utility exports calendar definitions in the Control-M/EM database to an output file for use as input to other utilities.
In fact, when the exportdefcal utility is invoked, an arguments file that you prepare is processed. This arguments file contains statements that specify an existing calendar or group of calendars. The calendars that you specified in the arguments file are exported to an output file. You can modify the exported calendars in the output file and re-import them into the Control-M/EM database using the defcal utility
To run the exportdefcal utility, you need to specify basic parameters shown before plus the below:

-arg <argFileName> -out <outFileName>

=> The argument file prepared is processed when the exportdefcal is invoked, this file should contains statements that specify an existing calendar or group of calendars.
=> Calendar(s) will be exported in the output file you specified as a parameter, this file definitions can be imported into a Control-M/EM using defcal utiliy for example.

Example: Export all calendars except one, from a datacenter

  1. Create an argument file exportcal.xml like the following:
    <TERMS>
    	<TERM>
    		<PARAM NAME="DATACENTER" OP="EQ" VALUE="DC_0"/>
    		<PARAM NAME="CALENDAR" OP="NEQ" VALUE="ALL_DAYS_CAL"/>
    		<PARAM NAME="TYPE" OP="EQ" VALUE="Periodic"/>
    	</TERM>
    </TERMS>
    

    Here I export all periodic calendars in the data center DC_0 and not equal to ALL_DAYS_CAL. See below the syntax to be respected.

  2. Use the same credentials.txt created above.
  3. Execute the command:
    emdef exportdeffolder -pf <passwordfile> -s <guiservername> -arg <argfilename> -out <outfilename>

    Which correspond to:

    emdef exportdeffolder -pf credentials.txt -s guiserverhostname -arg exportcal.xml -out DC_0_CAL_Def.xml

It is important to mention here the syntax to create the argument file:

  • TERMS
    These tags indicate the start and end of the TERMS file. Only criteria that are located between the tags are considered to be part of the argument!
  • TERM
    The TERM tags indicate the start and the end of a group of selection criteria used to specify a calendar or calendars that are to be exported.
  • Relationship between terms
    You can use AND and OR to join two terms.
  • Parameter name
    Parmeters name are fixed:
    – DATACENTER
    – CALENDAR
    – TYPE
  • Relationship between the NAME and the VALUE
    Valid values:
    – EQ
    – NEQ
    – NOTIN
    – LIKE
  • Value
    Of course, it should correspond to the parameter:
    -For DATACENTER: name of the Control-M installation
    -For CALENDAR: calendar name
    -For TYPE: Relative, Regular, Periodic, Rule_Based
  • defcal

    The defcal utility imports a calendar definition into the Control-M/EM database, it reads calendar definitions directly from a plain text input file in XML format, maybe generated in the step before? 🙂
    To run the exportdefcal utility, you need to specify basic parameters shown before plus the below one:

    -src <srcFileName>

    => The source file is a calendar(s) definition in a xml file

    Example: Export all calendars except one, from a datacenter

    1. Use the same credentials.txt created above.
    2. Execute the command:
      emdef defcal -pf <passwordFile> -s <guiServerName> -src <srcFileName>

      Which correspond to:

      emdef defcal -pf credentials.txt -s guiserverhostname -src DC_0_CAL_Def.xml

    As you saw this utility may be so useful to automate your work and standardize your calendars across all environments. My colleague Nabil talked about calendars management in this blog. In the next blog I will talk about emdef utility with folders. And you? Did you already use it? Don’t hesitate to share your experience and ask questions 😉