Infrastructure at your Service

David Diab

Control-M/EM – emdef utility – Jobs

By February 12, 2020 Control-M No Comments

The emdef is a command line utility used to make various modifications to job definitions in the Control-M/EM database. we saw how emdef can help to manage Calendars and Folders, today it the Jobs turn so let’s deep in 😉

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

  • exportdefjob: Exports job processing definitions to an output file
  • defjob: Imports job processing definitions
  • copydefjob: Creates a new job definition similar to a specified existing definition
  • duplicatedefjob: Makes a copy of an existing job definition in the same data center
  • deldefjob: Deletes specified job processing definitions

Basic parameters definition

Basic parameters not change between calendars and folders methods, so 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

exportdefjob

The exportdefjob utility exports job processing definitions from a folder in the Control-M/EM database to an output file. It processes a specified file of arguments in XML format which contains statements that identify existing job processing definitions. The identified definitions are exported from the Control-M/EM database to an output file.
Then the output file can be used as an input file in the same datacenter or in another one, depending on your needs.

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

-arg <argFileName> -out <outputFileName>

=> -arg: to specify the argument xml file that contains the jobs definitions
=> -out: Path and name of the file containing the exported job specifications.

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
    Parameters name are fixed:
    – DATACENTER
    – JOBNAME
    – CYCLIC
    Many other parameters are possible
  • Relationship between the NAME and the VALUE
    Valid values:
    – EQ
    – NEQ
    – LIKE
  • Value
    The value that correspond to the parameter (DATACENTER, JOBNAME, aso)

defjob

defjob method reads job processing definitions from a plain text input file written in XML format, then imports job processing definitions directly into Control-M/EM database.

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

-src <srcFileName> [/a]

=> -src: to specify the imput xml file that contains the folders definitions
=> /a: directs the utility to automatically reset the “Created By” parameter to the current Control-M/EM user when these two values do not match – OPTIONAL

Example: Import jobs from and XML Input file

  1. Create a source file:
    You can imagine the number of parameters and possibilities to create such a file… That’s why I never create it from scratch, usually I export a job similar to the one to be created using exportdefjob method, then I update its content. As you know, each job processing definition has a JOBISN field that contains a job ID number. In fact, the JOBISN is the JOB_ID field in the def_job folder, many jobs can have the same JOBISN number but it should be unique in each Folder.
    So, here we need to be careful guys! You can use the Control-M Workload Automation folder manager to determine the job ID. Double-click the required folder to get the job list, including the jobs IDs.
    If a job that is being imported contains a JOBISN number that already exists in the Control-M/EM database, defjob overwrites the existing job processing definition with the new job processing definition. If a JOBISN value is not specified, defjob imports the job processing definition as a new job.
    In my case I will simply use the file exported using the exportdefjob method.
  2. Create password file credentials.txt:
    user=emuser
    password=MyEmUserPass
    
  3. Execute the command:
    emdef defjob -pf <passwordFile> -s <guiServerName> -src <srcFileName>

    Which correspond to:

    emdef defjob -pf credentials.txt -s guiserverhostname -src JobsExport.xml 

copydefjob

The copydefjob parameter of the emdef utility creates a new job definition in the Control-M/EM database that is similar to a specified existing definition. The original job and the copy must be in different data centers or SMART Folders. To run the copydefjob utility, see Running the copydefjob utility. Multiple jobs can be selected and copied using the * wildcard character.

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

-arg <argFileName> [/a]

=> -arg: To specify the argument xml file that contains the jobs definitions
=> /a: directs the utility to automatically reset the “Created By” parameter to the current Control-M/EM user when these two values do not match – OPTIONAL

Below I listed some argument files example to better understand the content:
Example 1: Copy job processing definitions in the FOL1 if FOLDER_DSN is Lib1 and JOBNAME is Job1. In the copy, the FOLDER_DSN value is changed to Lib1_COPY.

<COPYJOB>
	<FOLDER_NAME FROM="FOL1"/>
	<FOLDER_DSN FROM="Lib1" TO="Lib1_COPY"/>
	<JOBNAME FROM="Job1"/>
</COPYJOB>

Example 2: Copies of all jobs in the FOL1 folder to the FOL3 folder.

<COPYJOB>
	<FOLDER_NAME FROM="FOL1" TO="FOL3"/>
</COPYJOB>

Exemple 3: Copy all cyclic jobs in the GR1 group that have a jobname beginning with the string JOBa from FOLDER_DSN Lib1 to FOLDER_DSN Lib1_DEST.

<COPYJOB>
	<FOLDER_DSN FROM="Lib1" TO="Lib1_DEST">
	<SUBAPPLICATION FROM="GR1"/>
	<CYCLIC FROM="1"/>
	<JOBNAME="JOBa*" />
</COPYJOB>

duplicatedefjob

At first sight, the duplicatedefjob method seems doing the same functionality as copydefjob, in fact, the only difference between both is that duplicatedefjob makes a copy of an existing job definition in the same data center and Folder which is not the case of copydefjob.
The rest remain the same between for both methods.

deldefjob

The deldefjob utility deletes specified job processing definitions in the Control-M/EM database. Like previous methods, this one take as entry a arguments XML file with parameters, all jobs that match the arguments file are deleted when the method is executed.

I am not going to explain in details all methods, I think the principle is crystal clear now on what is the benefit and how it can be done. It’s your turn to try if it is not already done, anyway don’t hesitate to share with us your experience 🙂

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

David Diab
David Diab

Consultant