duplicatedefjob

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 duplicatedefjob utility makes a copy of an existing job definition in the same data center and SMART folder. Elements of the copy can be changed. To copy jobs using the duplicatedefjob utility, see Copying Existing Jobs Using the duplicatedefjob Utility.

Multiple jobs can be selected and copied using the * wildcard character. For an explanation of how wildcards function in XML-based utilities, see Wildcards.

When duplicatedefjob is invoked, it processes a specified file of arguments in XML format. This file contains statements that identify existing job processing definitions. The identified definitions are copied, changes to the copy (if requested) are made, and the copy is stored in the Control-M/EM database. For more information, see duplicatedefjob XML File Rules.

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

Copying Existing Jobs Using the duplicatedefjob Utility

The following procedure describes how to copy an existing job definition in the same data center and SMART folder using the duplicatedefjob utility.

Begin

  1. Do one of the following:

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

    • Windows: Open a command prompt window where Control-M/EM is installed. 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 duplicatedefjob [-USERNAME <user> [-PASSWORD <password>] | -PASSWORD_FILE <password file>] -HOST <GUI Server Name> -ARG_FILE <XML file name> [/a] [-vv 2]

    • emdef duplicatedefjob [-u <user> [-p <password>] | -pf <password file>] -s <GUI Server Name> -arg <XML file name> [/a] [-vv 2]

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

For details about the duplicatedefjob parameters and switches, see emdef General Parameters and emdef Switches.

duplicatedefjob XML File Rules

The duplicatedefjob utility can use simple job parameters as search and replace criteria. Complex parameters, such as the name of an In Condition parameter or the degree of urgency of a Do Shout parameter, cannot be used as search criteria or modified with the duplicatedefjob utility.

For instructions about preparing this file, see XML File Rules.

The following rules apply to the arguments file for the duplicatedefjob utility:

  • More than one job can be specified in a duplicatedefjob file.

  • The arguments file is case-sensitive.

  • All parameter values must be enclosed in quotation marks (for example, JOBNAME="Job1").

  • Only one DUPLICATEJOB parameter can be used in the arguments file. This parameter must not contain more than one instance of each job parameter.

  • Multiple values can be specified for TO and FROM by using the * wildcard character. For an explanation of how wildcards function in the XML-based utilities, see Wildcards.

  • If any FROM value contains *, and the corresponding TO value contains *, the * in the TO value expresses the same information as the * in the FROM value.

  • Changing the data center name or SMART folder name causes the copy of the job scheduling definition to be imported into the specified data center or SMART folder.

Most job definition parameters in the arguments file are optional. However, note the following:

  • For each parameter that is specified, the FROM sub-parameter is mandatory and the TO sub-parameter is optional.

  • When FROM is specified without a TO, the FROM value is used as a filter criterion.

  • The FROM value is used as a search criteria for selecting jobs to copy. For example, JOBNAME FROM="Job2" copies all jobs with the JobName Job2

  • When TO is included, it specifies the value to which the parameter is set. For example, JOBNAME FROM="Job2" TO="Job2B" modifies all jobs with JobName Job2 so that they now have JobName Job2B.

The duplicatedefjob arguments file is checked and processed. If the file contains errors, a message is displayed specifying the lines with the errors.

duplicatedefjob XML File Parameters

The following table describes the duplicateddefjob arguments XML file parameters:

The first two lines of the arguments file specify the XML version, the text encoding format being used, and the location of the .dtd file.

Parameter

Description

DUPLICATEJOB

Indicates the start and end of a group of selection criteria for a job or jobs that are to be copied. Only criteria that are located between the DUPLICATEJOB tags are considered to be part of the duplicatedefjob parameters.

FOLDER_NAME

Defines the name of the SMART folder that the job belongs to.

At least one of the following SMART folder parameters must be included in the arguments file: DATACENTER, FOLDER_NAME, FOLDER_DSN

FOLDER_NAME FROM="Tbl5NYC"

Folder_DSN

(z/OS Only) Defines the name of the library that contains the SMART folder.

A TO sub-parameter cannot be specified for this parameter.

At least one of the following SMART folder parameters must be included in the arguments file: DATACENTER, FOLDER_NAME, FOLDER_DSN

FOLDER_DSN FROM="Lib1"

DATACENTER

Defines the name of the Control-M installation that the job belongs to.

A TO parameter cannot be specified for this parameter.

At least one of the following SMART folder parameters must be included in the arguments file: DATACENTER, FOLDER_NAME,FOLDER_DSN

DATACENTER FROM="CTMNYC"

FOLDER_ORDER_ METHOD

String. Mandatory.

A TO parameter can be specified and modified for this parameter.

FOLDER_ORDER_ METHOD FROM="Job3"

JOBNAME

Defines the name of the job.

JOBNAME FROM="Job3" TO="Job3_COPY"

FILE_NAME

Defines the name of the file that contains the job script.

FILE_NAME FROM="Mem3" TO="Mem7"

SUB_APPLICATION

Defines the name of the group that the job belongs to. Used as a descriptive name for related jobs.

SUB_APPLICATION FROM="Grp_HR" TO="Grp_ACCT"

  • FROM: Mandatory

  • TO: Optional

APPLICATION

Defines the name of the application that the job group belongs to. Used as a descriptive name for related jobs.

APPLICATION FROM="App3" TO="App1"

TASKTYPE

Describes the type of job (task) to be performed by Control-M.

TASKTYPE FROM="Detached" TO="Job"

  • FROM: Mandatory

    Valid Values:

    • Job

    • Detached

    • Command

    • Dummy

    (z/OS Only) Valid Values:

    • Started_Task

    • Cyclic_Job

    • Cyclic_Task

    • Emergency_Job

    • Emergency_Cyclic_Job

    • Emergency_Task

    • Emergency_Cyclic_Task

  • TO: Optional.

    Valid Values: Same as FROM values.

CREATED_BY

Defines the Control‑M/EM user who defined the job.

This argument is used by the Control‑M/Server security mechanism. Under certain circumstances, it cannot be modified. For more information, see the Security chapter and the description of the AuthorSecurity system parameter in GUI Server Parameters.

CREATED_BY FROM="emuser" TO="em5"

FILE_PATH

Defines the name of the library/directory that contains the job script.

FILE_PATH FROM="File1" TO="File4"

CMDLINE

Describes the Command string supplied when the job Task Type is Command.

CMDLINE FROM="C:\Format" TO="C\:CD Emnt"

HOSTID

Defines the name of an Agent computer or a host group that the job is submitted to.

HOSTID FROM="Com3" TO="Acct4"

  • FROM: Mandatory

  • TO: Host name of the Agent computer that is running the job.

RUN_AS

Defines the owner user ID associated with the job. This parameter is used by the Control-M/Server security mechanism.

OWNER FROM="emuser" TO="emhr"

  • FROM: Mandatory

  • TO: Optional

MAXRERUN

Determines the maximum number of reruns that can be performed for the job.

MAXRERUN FROM="1" TO="3"

TIMEFROM

Earliest time for submitting the job. Optional.

TIMEFROM FROM="1430" TO="1450"

TIMETO

Determines the latest time for submitting the job. Optional.

TIMETO FROM="1600" TO="1620"

DUE_OUT

Time that the job is expected to finish. Optional.

DUE_OUT FROM="1500" TO="1530"

PRIORITY

Control-M job priority. Optional.

PRIORITY FROM="AA" TO="1A"

CRITICAL

Indicates whether the job is a critical-path job in Control-M.

CRITICAL FROM="0" TO="1"

  • FROM: Mandatory

    Valid Values:

    • 0: No

    • 1: Yes

    Default: 0

  • TO: Optional.

    Valid Values:

    • 0: No

    • 1: Yes

    Default: 0

CYCLIC

Indicates whether the job is cyclic (to be run at regular intervals). Optional.

CYCLIC FROM="0" TO="1"

  • FROM: Mandatory.

    Valid Values:

    • 0: No

    • 1: Yes

    Default: 0

  • TO: Optional.

    Valid Values:

    • 0: No

    • 1: Yes

    Default: 0

CYCLIC_TYPE

Determines the type of cyclic job:

  • Interval

  • IntervalSequence

  • SpecificTimes

CYCLIC_TOLERANCE

Determines the maximum delay in minutes permitted for a late submission when selecting a specific time.

CYCLIC_INTERVAL_SEQUENCE

Defines a list of time intervals, separated by commas, of up to 4000 characters including commas.

+30M,+2H,+1D

CYCLIC_TIMES_SEQUENCE

Defines a list of times, separated by commas.

0800,1330,2300

CONFIRM

Indicates whether the job must be manually confirmed by the Control‑M/EM user before it runs.

CONFIRM FROM="0" TO="1"

  • FROM: Mandatory

    Valid Values:

    • 0: No

    • 1: Yes

    Default: 0

  • TO: Optional

    Valid Values:

    • 0: No

    • 1: Yes

    Default: 0

AUTOARCH

Determines whether SYSDATA is to be archived.

AUTOARCH FROM=0" TO="1"

  • FROM: Mandatory

    Valid Values:

    • 0: No

    • 1: Yes

      Default: 0

  • TO: Optional

    Valid Values:

    • 0: No

    • 1: Yes

    Default: 0

INTERVAL

Determines the time to wait between reruns or cyclic runs of a job.

INTERVAL FROM="3" TO="4"

OVERRIDE_PATH

Defines the name of an alternate job script library/directory.

OVERRIDE PATH FROM="lib3" TO="lib4"

MAXWAIT

Determines the number of extra days after the original scheduling date that the job is allowed to remain in the Active Jobs database awaiting execution.

MAXWAIT FROM="4" TO="3"

DESCRIPTION

Describes the job in free text.

DESCRIPTION FROM="data backup from 120399" TO="data backup from 021400"

DOCMEM

Defines the name of the file containing job documentation.

DOCMEM FROM="mem4" TO="Mem67"

DOCLIB

Defines the name of a library or directory containing the job documentation file.

DOCLIB FROM="AcctFiles" TO="HRFiles"

DAYS

Determines the days of the month to order the job.

DAYS FROM="ALL" TO="159"

DAYS_AND_OR

Determines the relationship between specified Days values and Weekdays values.

DAYS_AND_OR FROM="AND" TO="OR"

WEEKDAYS

Determines the days of the week to order the job.

WEEKDAYS FROM="1,2,4" TO="ALL"

DATE

Specifies dates to order the job, written in mmdd format.

DATE FROM="0312" TO="0319"

DAYSCAL

Defines a user-defined calendar used to specify a set of days.

DAYSCAL FROM="shipping" TO="receiving"

WEEKSCAL

Defines a calendar to be used to validate specified weekdays to order the job.

WEEKSCAL FROM="w5" TO="w6"

CONFCAL

Specifies a calendar that is used to validate all specified days and dates to schedule the job.

CONFCAL FROM="cal99" TO="cal00"

RETRO

Indicates whether the job is scheduled for possible execution after its original scheduling date (odate) has passed.

RETRO FROM="0" TO="1"

  • FROM: Mandatory

    Valid Values:

    • 0: No

    • 1: Yes

    Default: 0

  • TO: Optional

    Valid Values:

    • 0: No

    • 1: Yes

    Default: 0

SHIFT

Describes how to shift the scheduling date of the job.

SHIFT FROM="PREVDAY" TO="NEXTDAY"

  • FROM: Mandatory

    Valid Values:

    • IGNOREJOB

    • PREVDAY

    • NEXTDAY

    • NOCONFCAL

  • TO: Optional

    Valid Values: Same as FROM.

SHIFTNUM

Determines the number of days to shift the scheduling date of the job.

SHIFTNUM FROM="-10" TO="5"

MAXDAYS

Determines the maximum number of days to retain the SYSDATA archive dataset for jobs that ended NOTOK. Sub-parameter of AUTOARCH.

MAXDAYS FROM="07" TO="14"

MAXRUNS

Determines the maximum number of job runs to retain the SYSDATA archive dataset for jobs that ended NOTOK. Sub-parameter of AUTOARCH.

MAXRUNS FROM="100" TO="250"

RERUNMEM

(z/OS Only) Defines the JCL member to use when the job is automatically rerun. 1 - 8 characters.

RERUNMEM FROM="Mem45" TO="Mem7"

RETEN_DAYS

(z/OS Only) Determines the number of days to retain the job in the History Jobs file.

RETEN_DAYS FROM="5" TO="7"

RETEN_GEN

(z/OS Only) Determines the maximum number of generations to keep in the History Jobs file.

RETEN_GEN FROM="3" TO="4"

PREV_DAY

PREV_DAY FROM="N" TO="Y"

  • FROM: Mandatory

    Valid Values:

    • Y

    • N

  • TO: Optional

    Valid Values:

    • Y

    • N

IND_CYCLIC

Indicates whether the time interval between runs of a cyclic job is counted from the start or the end of the previous job run.

IND_CYCLIC FROM="Y" TO="N"

  • FROM: Mandatory

    Valid Values:

    • START

    • END

  • TO: Optional

    Valid Values:

    • START

    • END

RULE_BASED_CALENDAR_RELATIONSHIP

Defines the relationship (AND|OR) between the specified Rule-Based Calendar and the basic scheduling criteria of the job.

RULE_BASED_CALENDAR_RELATIONSHIP FROM="AND" TO="OR"

  • FROM: Mandatory

    Valid Values:

    • AND

    • OR

  • TO: Optional

    Valid Values:

    • AND

    • OR

TAG_RELATIONSHIP

Defines the relationship (AND|OR) between the specified Schedule Tag criteria and the basic scheduling criteria of the job. This parameter is relevant only for jobs in a SMART folder. This parameter is for backward compatibility.

TAG_RELATIONSHIP FROM="AND" TO="OR"

  • FROM: Mandatory

    Valid Values:

    • AND

    • OR

  • TO: Optional

    Valid Values:

    • AND

    • OR

SYSDB

Determines whether single or multiple data sets are used to catalogue sysdata.

SYSDB FROM="1" TO="0"

  • FROM: Mandatory

    Valid Values:

    • 0: Multiple

    • 1: Single

    Default: 0

  • TO: Optional

    Valid Values:

    • 0: Multiple

    • 1: Single

    Default: 0

PDSNAME

Defines the name of partitioned dataset (PDS) to be checked for free space.

PDSNAME FROM="Lib_3" TO="Lib_5"

MINIMUM

Determines the minimum number of free partitioned dataset tracks required by the library specified for the PDSNAME parameter.

MINIMUM FROM="5" TO="6"

CATEGORY

Defines the name of a Control-D report decollating mission category that must be scheduled under Control-D when the job is scheduled under Control-M.

CATEGORY FROM="*" TO="DAILY"

PREVENTNCT2

(z/OS Only) Prevents dataset clean up before the original job run.

Valid Values:

  • Blank: Does not perform data set clean up before the original job run. Default.

  • N: Does not prevent clean up.

  • Y: Prevents data set clean up. This value is not valid for started tasks.

  • L: List. Do not perform data set clean up before the original job run. Do generate messages that would be required for CDG adjustment during restart.

  • F: Flush. Halt processing of the job if any data set clean up error is detected, even if z/OS would not have stopped processing the job.

PREVENTNC2 FROM="1" TO="0"

  • FROM: Mandatory

    Valid Values:

    • 0: Do not prevent

    • 1: Prevent

    Default: 0

  • TO: Optional

    Valid Values:

    • 0: Do not prevent

    • 1: Prevent

    Default: 0

JAN - DEC

Determines the months when the job can run. Excluding a month is the same as including that month with the value 0.

JAN FROM="0" TO="1"

JUL FROM="0" TO="1"

  • FROM: Mandatory.

    Valid Values:

    • 0: Do not run the job

    • 1: Run the job

      Default: 0

  • TO: Optional.

    Valid Values:

    • 0: Do not run the job

    • 1: Run the job

      Default: 0

OPTION

Defines job output handling options.

OPTION FROM="Copy" TO="Release"

  • FROM: Mandatory.

    Valid Values:

    • Release

    • Delete

    • Copy

    • Move

    • File

    • NewDest

    • ChangeClass

  • TO: Optional.

    Valid Values: same as FROM.

PAR

Retains additional information supplied for certain OPTION values such as Release and NewDest.

PAR FROM="mem3log" TO="mem5log"

FROM

Limits the OUTPUT handling operation to OUTPUTs from the specified class.

FROM FROM="1" TO="2"

ADJUST_COND

Indicates whether to ignore prerequisite conditions normally set by predecessor jobs if the relevant predecessor jobs are not scheduled. This parameter is relevant only for jobs in a SMART folder.

ADJUST_COND FROM="1" TO="0"

Valid Values:

  • 0: Do not ignore

  • 1: Ignore relevant prerequisite conditions

    Default: 0

APPL_TYPE

Defines the type of external application, such as SAP or Oracle, that the job runs on. Mandatory for external application jobs. Up to 10 characters.

APPL_TYPE FROM="SAP" TO="OracleApps"

APPL_VER

Defines the version of an external application, such as SAP or Oracle, that the job runs on. Mandatory for external application jobs. Up to 10 characters.

APPL_VER FROM="4.5" TO="4.6"

APPL_FORM

Defines the predefined set of external application parameters that are displayed in the Job Properties team. Mandatory for external application jobs. Up to 30 characters.

APPL_FORM FROM="Default SAP 4.6" TO="Default SAP 4.5"

CM_VER

Defines the version of the external Application Add-on, such as SAP or Oracle, that is installed in the Control-M installation. Mandatory for external application jobs. Up to 10 characters.

CM_VER FROM="6.1.00" TO="6.1.01"

MULTY_Agent

Determines whether to broadcast job submission details to all Agents in a specified Host Group.

MULTY_Agent FROM="N" TO="Y"

  • Valid Values:

    • Y: Run as multi-Agent job

    • N: Do not run as multi-Agent job.

      Default: N

ACTIVE_FROM

(z/OS Only) Determines the date when the job or SMART folder can be ordered. Date Format: YYYYMMDD

ACTIVE_FROM FROM="20210315" TO="20220601"

ACTIVE_TILL

(z/OS Only) Determines the date when the job or SMART folder can no longer be ordered. Date Format: YYYYMMDD

ACTIVE_TILL FROM="20210315" TO="20210601"

TIMEZONE

Defines the global time zone used to calculate the interval for time-related conditions. Default: GMT

TIMEZONE FROM="EST" TO="GMT"

SYSTEM_AFFINITY

JES2: Identifies the system that the job must be initiated and executed on.

JES3: Identifies the processor that the job must executes on.

SYSTEM_AFFINITY FROM="SYS3"

SYSTEM_AFFINITY FROM="SYS3" TO="SYS6"

REQUEST_NJE_HOST

Defines the Host in the JES network that the job is to execute on.

REQUEST_NJE_HOST="OS5"

REQUEST_NJE_HOST FROM="OS5" TO="OS6"

SCHEDULING_ENVIRONMENT

(z/OS Only) Indicates the JES2 workload management scheduling environment associated with the job.

SCHEDULING_ENVIRONMENT FROM="SCHD2"

SCHEDULING_ENVIRONMENT FROM="SCHD2" TO="SCHD3"

CREATION_USER

Identifies the name of the user that created the job.

CREATION_USER FROM="emuser" TO="em1"

CREATION_DATE

Determines the date that the job was created.

CREATION_DATE FROM="1212" TO="2012"

CREATION_TIME

Determines the time that the job was created.

CREATION_TIME FROM="1230" TO="1430"

CHANGE_USERID

Identifies the name of the user that last modified the job.

CHANGE_USERID FROM="emuser" TO="emacct"

CHANGE_DATE

Determines the date that the job was last modified.

CHANGE_DATE FROM="1204" TO="1304"

CHANGE_TIME

Determines the time that the job was last modified.

CHANGE_TIME FROM="1650" TO="1700"

Copy and Modify Definitions XML File Example

In the duplicatedefjob XML file, copy job processing definitions from the Tbl5NYC SMART folder that has FOLDER_DSN Lib1 and JOBNAME Job3. Change FOLDER_DSN to Lib1_COPY and change JOBNAME Job3 to Job3_COPY. Store the changed definitions in the same SMART folder.

Copy 
<DUPLICATEJOB>
<FOLDER_NAME FROM="Tbl5NYC"/>
<FOLDER_DSN FROM="Lib1" TO="Lib1_COPY"/>
<JOBNAME FROM="Job3" TO="Job3_COPY"/>
</DUPLICATEJOB>

Duplicate Jobs Based on Several Criteria duplicatedefjob XML File Example

Copy all cyclic jobs in the GrpAcct group whose jobname begins with "Acct". Append "_COPY" to the job name of each copied job.

Copy 
<DUPLICATEJOB>
<SUBAPPLICATION FROM="GrpAcct"/>
<CYCLIC FROM="1"/>
<JOBNAME FROM="Acct*" TO="Acct*_COPY"/>
</DUPLICATEJOB>