copydefjob

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 copydefjob utility copies jobs from one folder to another 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 create a new job using the defjob utility, see Copying Jobs to and from Folders Using the copydefjob Utility.

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

When copydefjob is invoked, it processes a file of arguments that specifies criteria for selecting one or more existing job processing definitions. The selected jobs are copied to the existing SMART folder and/or data center specified in the arguments file. For more information, see copydefjob XML File Rules.

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

Copying Jobs to and from Folders Using the copydefjob Utility

This procedure describes how to copy job definitions from one folder to another folder using the copydefjob 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. Type one of the following commands:

    • emdef copydefjob [-USERNAME <user> [-PASSWORD <password>] | -PASSWORD_FILE <password file>] -HOST <GUI Server Name> -ARG_FILE <XML file name> [/a] [-vv 2]

    • emdef copydefjob [-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 copydefjob parameters and switches, see emdef General Parameters and emdef Switches.

copydefjob XML File Rules

Arguments are used as selection criteria to determine which jobs to copy. Arguments are written to the copydefjob argument file. The arguments files that you create with the copydefjob utility are written in XML format and saved in a text file. Instructions for preparing this file are in XML file preparation.

When this file is invoked, job processing definitions are exported from the Control-M/EM database.

Each parameter that you specify must have a FROM value. This value is used as a search criteria for selecting jobs to copy.

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

The following rules apply to the copydefjob utility arguments file:

  • More than one job can be specified in the arguments file.

  • The arguments file is case-sensitive.

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

  • Only one COPYJOB parameter can be used in an arguments file.

  • The COPYJOB parameter must contain only one of each job parameter. Many job parameters are optional.

  • 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 a * and the corresponding TO value contains a *, the * in the TO value represents the same information the * in the FROM value.

  • Changing the data center name or the SMART folder name imports the copy of the job into a data center or SMART folder different from the one in which the original job was located.

Most job definition parameters are optional. However note the following:

  • If you specify any parameters, the FROM sub-parameter is mandatory and the TO sub-parameter is optional.

  • If a FROM value is specified without a TO value, it is used as a filter criterion.

  • If a TO value is specified, it indicates the new value of the parameter.

copydefjob XML File Parameters

The following table lists input file parameters for the copydefjob utility:

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

COPYJOB

Indicates the start and end of the COPYJOB argument. Only criteria that are located between the tags are considered to be part of the argument.

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" TO="Tbl7NYC"

FROM: Name of the SMART folder specified in the job processing definition that is being copied.

TO: The folder name in the job processing definition copy.

FOLDER_DSN

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

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" TO="Lib1_COPY"

FROM: Name of the library containing the SMART folder in the job processing definition that is copied.

TO: Name of the library in the job processing definition copy.

DATACENTER

Defines the name of the Control-M installation 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

DATACENTER FROM="EM_Montreal" TO="EM_Paris"

FROM: Name of the Control-M installation to which the job being copied belongs. (Mandatory)

TO: Name of the Control-M installation to which the job copy belongs. (Optional)

JOBNAME

Defines the name of the job processing definition.

JOBNAME FROM="Job3"

FILE_NAME

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

FILE_NAME FROM="Mem3"

SUB_APPLICATION

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

SUB_APPLICATION FROM="Grp_HR"

APPLICATION

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

APPLICATION FROM="App3"

TASKTYPE

Defines the type of the job (task) that Control-M performs.

TASKTYPE FROM="Detached"

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
FOLDER_ORDER_METHOD

Optional.

FOLDER_ORDER_ METHOD FROM="Job3"

CREATED_BY

Defines the Control-M/EM user who created the job.

This argument is used by the Control-M/Server security mechanism and, under certain circumstances, 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"

FILE_PATH

Defines the name of the library/directory in which the job script resides.

FILE_PATH FROM="Mem1"

CMDLINE

Defines the command supplied when the job Task Type is Command.

CMDLINE FROM="C:\Format"

HOSTID

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

HOSTID FROM="Com3"

RUN_AS

Defines the Run_As name associated with the job. This parameter is used by the Control-M/Server security mechanism.

RUN_AS FROM="emuser"

MAXRERUN

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

MAXRERUN FROM="1"

Valid Values: 0-99.

Default: 0

TIMEFROM

Indicates the earliest time for submitting the job.

TIMEFROM FROM="1430"

TIMETO

Indicates the latest time for submitting the job.

TIMETO FROM="1600"

DUE_OUT

Time that the job is expected to finish.

DUE_OUT FROM="1500"

PRIORITY

Indicates Control-M job priority.

PRIORITY FROM="AA"

CRITICAL

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

CRITICAL FROM="0"

Valid Values:

  • 0

  • 1

    Default: 0

CYCLIC

Indicates if the job is cyclic (to be rerun at regular intervals).

CYCLIC FROM="0"

Valid Values:

  • 0

  • 1

    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

Example: 5 minutes

CYCLIC_INTERVAL_ SEQUENCE

Defines a list of time intervals, separated by commas, such as +30M,+2H,+1D. Up to 4000 characters, including commas.

CYCLIC_TIMES_SEQUENCE

Defines a list of times, separated by commas, such as 0800,1330,2300, which supports the time synonym, such as 2730.

CONFIRM

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

CONFIRM FROM="0"

Valid Values:

  • 0

  • 1

    Default: 0

AUTOARCH

Determines whether SYSDATA is to be archived.

AUTOARCH FROM=0"

Valid Values:

  • 0

  • 1

  • Default: 0

INTERVAL

Specifies the length of time (in minutes) to wait between reruns of a job or between cyclic runs of a job. Integer.

INTERVAL FROM="3"

OVERRIDE_PATH

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

OVERRIDE PATH FROM="lib3"

MAXWAIT

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

MAXWAIT FROM="4"

DESCRIPTION

Describes the job.

DESCRIPTION FROM="data backup from 120399"

DOCMEM

Defines the name of the file containing job documentation.

DOCMEM FROM="mem4"

DOCLIB

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

DOCLIB FROM="AcctFiles"

DAYS

Determines the days of the month to order the job.

DAYS FROM="ALL"

DAYS_AND_OR

Indicates the relationship between specified Days values and Weekdays values.

DAYS_AND_OR FROM="AND"

WEEKDAYS

Determines the days of the week to order the job.

WEEKDAYS FROM="1,2,4"

DATE

Determines specific dates to order the job. MMDD format.

DATE FROM="0312"

DAYSCAL

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

DAYSCAL FROM="shipping"

WEEKSCAL

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

WEEKSCAL FROM="2"

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 (ODATEClosed The date that a job joins the Run Queue.) has passed.

RETRO FROM="0"

Valid Values:

  • 0: No

  • 1: Yes

    Default: 0

SHIFT

Describes how to shift the scheduling date of the job.

SHIFT FROM="PREVDAY"

Valid Values:

  • IGNOREJOB

  • PREVDAY

  • NEXTDAY

  • NOCONFCAL

SHIFTNUM

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

SHIFTNUM FROM="-10"

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"

MAXRUNS

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

MAXRUNS FROM="100"

RERUNMEM

Defines the name of the JCL member to use when the job is automatically rerun. 1-8 characters.

RERUNMEM FROM="Mem45"

RETEN_DAYS

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

RETEN_DAYS FROM="5"

RETEN_GEN

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

RETEN_GEN FROM="3"

TASK_CLASS

Defines the job class for the task.

TASK_CLASS FROM="Distribution"

Valid Values:

  • Distribution

  • Decollation

PREV_DAY

Indicates whether job scheduling is shifted to a previous working day in the CONFCAL calendar.

PREV_DAY FROM="N"

Valid Values:

  • Y

  • N

IND_CYCLIC

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

IND_CYCLIC FROM="START"

Valid Values:

  • START

  • END

RULE_BASED_CALENDAR_RELATIONSHIP

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

RULE_BASED_CALENDAR_RELATIONSHIP FROM="AND"

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"

Valid Values:

  • AND

  • OR

SYSDB

Determines whether one or multiple data sets are used to catalog sysdata.

SYSDB FROM="1" TO="0"

Valid Values:

  • 0: Multiple

  • 1: Single

    Default: 0

PDSNAME

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

PDSNAME FROM="Lib_3"

MINIMUM

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

MINIMUM FROM="5"

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="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).

PREVENTNCT2 FROM="1"

Valid Values:

  • 0

  • 1

Default: 0

JAN - DEC

Determines the months that the job can run. Optional.

JAN FROM="0"

Valid Values:

  • 0

  • 1

    Default: 0

OPTION

Defines the job OUTPUT handling options.

OPTION FROM="Copy"

Valid Values:

  • Release

  • Delete

  • Copy

  • Move

  • File

  • NewDest

  • ChangeClass

PAR

Holds additional information for certain OPTION FROM values, such as Release, NewDest.

PAR FROM="mem3.log"

FROM

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

FROM FROM="5"

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.

Valid Values:

  • 0: Do not ignore

  • 1: Ignore relevant prerequisite conditions

    Default: 0

APPL_TYPE

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

APPL_TYPE FROM="SAP"

APPL_VER

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

APPL_VER FROM="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"

CM_VER

Indicates the version of 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"

MULTY_Agent

Broadcasts job submission details to all Agents in a specified Host Group.

MULTY_Agent FROM="N"

Valid Values:

  • Y: run as multi-Agent job

  • N: not run as multi-Agent job.

Default: N

ACTIVE_FROM

(z/OS only) Indicates the start of a period of time that the job or SMART folder can be ordered.

Date Format: YYYYMMDD

ACTIVE_FROM FROM="20210315"

ACTIVE_TILL

(z/OS only) Indicates the end of a period of time during that the job or SMART folder can be ordered.

Date Format: YYYYMMDD

ACTIVE_TILL FROM="20210315"

TIMEZONE

Indicates global time zone used to calculate the interval for time-related conditions.

TIMEZONE FROM="EST"

Default: GMT

SYSTEM_AFFINITY

JES2: Identifies the system that initiates and executes the job.

JES3: Identifies the processor that executes the job.

SYSTEM_AFFINITY FROM="SYS3"

REQUEST_NJE_HOST

Specifies the host in the JES network that will execute the job.

REQUEST_NJE_HOST FROM="OS5"

SCHEDULING_ENVIRONMENT

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

SCHEDULING_ENVIRONMENT FROM="SCHD2"

CREATION_USER

Defines the name of the user who creates the job.

CREATION_USER FROM="emuser"

CREATION_DATE

Determines the date that the job is created.

CREATION_DATE FROM="1212"

CREATION_TIME

Determines the time that the job is created.

CREATION_TIME FROM="1230"

CHANGE_USERID

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

CHANGE_USERID FROM="emuser"

CHANGE_DATE

Determines the date that the job was last modified.

CHANGE_DATE FROM="1204"

CHANGE_TIME

Determines the time that the job was last modified.

CHANGE_TIME FROM="1650"

Copy Jobs and Parameter Values XML File Example

In the copydefjob arguments file, copy job processing definitions in the F15NYC folder if FOLDER_DSN is Lib1 and JOBNAME is Job3. In the copy, the FOLDER_DSN value is changed to Lib1_COPY.

Copy 
<COPYJOB><FOLDER_NAME FROM="F15NYC"/>
<FOLDER_DSN FROM="Lib1" TO="Lib1_COPY"/>
<JOBNAME FROM="Job3"/>
</COPYJOB>

Copy All Jobs in One Folder to Another Folder XML File Example

In the copydefjob XML file, copy all jobs in the F15NYC folder to the F17LA folder.

Copy 
<COPYJOB>
<FOLDER_NAME FROM="F15NYC" TO="F17LA"/>
</COPYJOB>

Copy All Cyclic Jobs with Similar Job Name XML File example

In the copydefjob XML file, copy all cyclic jobs in the GrpAcct Sub Application that have a JobName beginning with the string Acct from FOLDER_DSN 23Y to FOLDER_DSN 14G.

Copy 
<COPYJOB>
<FOLDER_DSN FROM="23Y" TO="14G">
<SUBAPPLICATION FROM="GrpAcct"/>
<CYCLIC FROM="1"/>
<JOBNAME="Acct*" />
</COPYJOB>

Copy Jobs in a Regular Folder to a SMART folder XML File Example

In the copydefjob XML file, copy all jobs in the RegFolder folder in the ctm918 data center to the GrpSFolder SMART folder.

Copy 
<COPYJOB>
<DATACENTER FROM="ctm918"/>
<FOLDER_NAME FROM="RegFolder" TO="GrpSFolder"/>
</COPYJOB>

Copying Jobs in a Folder to a SMART folder Using the copydefjob Utility

This procedure describes how to copy the jobs in a folder to a SMART folder using the copydefjob utility.

Begin

  1. From Control-M client, define a SMART folder that does not contain any jobs, and then Check In the SMART folder.

  2. Create a copydefjob arguments file in which jobs in a folder are copied to the SMART folder that you created by doing the following:

    1. Open a text editor and format the file using the specifications referred to in copydefjob XML File Parameters.

    2. Specify the Control-M installation in which the jobs to be copied reside using the DATACENTER parameter:

      DATACENTER FROM="CTM_Name"

    3. Specify that the Folder Name value of the jobs changes from the name of the folder to the name of the SMART folder.

      FOLDER_NAME FROM="Sched_Fl_Name" TO="Grp_Sched_Fl_Name"

    4. Save and close the file.

  3. In the command line, enter the copydefjob utility command that uses the file that you created in the previous step:

    copydefjob -u <user> [-p <password>] -s <GUI Server Name> -arg <XML file name>

  4. In Control-M client do the following:

    1. Click Load to upload the SMART folder to the Control-M/Server.

    2. Order the SMART folder.

    3. Verify that the SMART folder now contains the jobs that were copied to it.

      Delete the original folder if not needed.