deffolder

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 deffolder utility imports Folders and SMART folders into the Control-M/EM database.

When deffolder is invoked, a file of arguments that you have created is processed. This input file contains statements that specify:

  • An existing folder or set of folders.

  • An existing SMART folder or set of SMART folders.

For more information, see deffolder XML File Rules. The specified folders are imported into the Control-M/EM database.

The deffolder 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. 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.

If the folders do not exist in the Control-M/EM database, the utility creates them. If the folders do exist, a message is issued indicating that the folders already exist (unless the /o switch is specified, in which case the folders are overwritten – the /o switch is described below).

The deffolder utility reads folder and SMART folder definitions directly from a plain text arguments file (in XML format) instead of reading them from the command line.

A single deffolder input file can contain specifications for both folders and SMART folders.

XML is comprised of elements and attributes. Each element can contain attributes and sub-elements. In the folder that follows, elements are bolded and attributes are italicized.

Running the deffolder Utility

This procedure describes how to run the deffolder utility, which enables you to import folders and SMART folders into the Control-M/EM database.

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 deffolder [-USERNAME <user> [-PASSWORD <password>] | -PASSWORD_FILE <password file>] -HOST <GUI Server Name> -SRC_FILE <XML file name> [/a] [/o] [/f] [-vv 2]

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

For more details on the deffolder parameters and switches, see emdef General Parameters and emdef Switches.

deffolder XML File Rules

The deffolder XML file contains the definition of a folder. The file is written in XML format and saved in a text file. The format in which this file must be written is described on the following pages.

When this file is invoked, Folder and/or SMART folder definitions are imported to the Control-M/EM database. For instructions for creating input files, see XML File Rules.

The following rules apply to the deffolder XML file:

  • Only one SMART folder can be included in a folder. However, multiple folders can be included in a single input file. Each of these folders can contain one SMART folder.

  • Multiple SMART folders can be included in a file if the file only contains SMART folders.

  • More than one job can be specified in either type of folder.

  • A single XML file can contain both Folders and SMART folder parameters.

deffolder XML File Parameters for Folders

The following table lists the deffolder XML file parameters for Folders:

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 .xsd file.

DEFTABLE

Indicates to Control-M/EM database the beginning and end of the deffolder utility. Folder definitions are placed between the opening and closing DEFTABLE tags. One or more folders can be specified. Each individual folder is enclosed by the <FOLDER ENFORCE_VALIDATION><FOLDER> tags.

FOLDER

Indicates the closing tags of a single folder definition. In the case of the folder, the folder parameters consist of parameters that describe the folder directly and a list of the jobs that are included in the folder. In turn, each of the jobs that is listed includes all of its own descriptive parameters.

FOLDER ENFORCE_VALIDATION

Determines if validation is either an error or a warning.

Valid Values:

  • Y

  • N

Relevant for Control-M Workload Change Manager only.
FOLDER_ORDER_ METHOD

Defines the Newday or User daily name.
FOLDER_NAME

Defines the name of the folder to which the job belongs.

The following folder parameters must be specified for each folder:

  • DATACENTER

  • FOLDER_NAME

  • FOLDER_DSN (z/OS Only)
FOLDER_DSN

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

The following folder parameters must be specified for each folder:

  • DATACENTER

  • FOLDER_NAME

  • FOLDER_DSN (z/OS Only)
DATACENTER

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

The following folder parameters must be specified for each folder:

  • DATACENTER

  • FOLDER_NAME

  • FOLDER_DSN (z/OS Only)
LAST_UPLOAD

Determines the date of the last folder upload.
JOB

Indicates opening and closing tags of a single job definition. Parameters of the job are listed between the tags. For a complete listing of deffolder parameters, see defjob.

SITE_STANDARD_NAME

Defines the name of the site standard that is applied to the folder and all of its entities. For more information see Site Standards

Relevant for Control-M Workload Change Manager only.

BUSINESS_PARAMETER_NAME

Defines the name of the Business Parameter name that is applied to the folder and all of its entities. For more information, see Site Standards

Relevant for Control-M Workload Change Manager only.

VALUE

Defines the value of a customer defined business field. String.

Relevant for Control-M Workload Change Manager only.

deffolder XML File Parameters for SMART folders

The following table lists the deffolder input file parameters for SMART folders:

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 .xsd file.

DEFTABLE

Indicates the beginning and end of the deffolder utility. Folder definitions are placed between the opening and closing DEFTABLE tags. One or more jobs can be specified. Each individual job is enclosed by the <SMART_FOLDER ENFORCE_VALIDATION></SMART_FOLDER> tag.

SMART_FOLDER

Indicates the closing tags of a SMART folder definition.

SMART_FOLDER ENFORCE_VALIDATION

Determines if validation is either an error or a warning.

Valid Values:

  • Y

  • N

Relevant for Control-M Workload Change Manager only.

JOBISN

For internal use.

JOBISN is the JOB_ID field in the def_job folder. Many jobs can have the same JOBISN number. However, the JOBISN number is unique in each Folder. Select the job in the Monitoring domain to see jobs IDs.

FOLDER_NAME

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

The following SMART folder parameters must be specified for each folder:

  • DATACENTER

  • FOLDER_NAME

  • FOLDER_DSN (z/OS Only)

FOLDER_ORDER_ METHOD

Defines the New day or User daily name.

DATACENTER

Name of the Control-M installation to which the SMART folder belongs.

The following folder parameters must be specified for each folder:

  • DATACENTER

  • FOLDER_NAME

  • FOLDER_DSN (z/OS Only)

FOLDER_DSN

(z/OS Only) Library for the folder. String. Optional.

The following folder parameters must be specified for each folder:

  • DATACENTER

  • FOLDER_NAME

  • FOLDER_DSN (z/OS Only)

REAL_FOLDER_ID

For internal use only. Do not include this parameter in your deffolder input file.

CYCLIC

Indicates whether the job is cyclic—to be run at regular intervals.

Valid Values:

  • 0: No

  • 1: Yes

Default: 0

CYCLIC_TOLERANCE

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

5 minutes

CYCLIC_TYPE

Determines the type of cyclic job:

  • C: CYCLIC_TOLERANCE

  • V: CYCLIC_INTERVAL_SEQUENCE

  • S: CYCLIC_TIMES_SEQUENCE

CYCLIC_INTERVAL_SEQUENCE

A list of time intervals, separated by commas up to 4000 characters.

+30M,+2H,+1D

CYCLIC_TIMES_SEQUENCE

Determines a list of times, separated by commas.

0800,1330,2300

LAST_UPLOAD

Determines the date of the last folder upload.

REMOVEATONCE

Indicates that all jobs in the folder are not removed automatically from the Active Jobs database. Instead jobs wait for the folder to complete and are removed at the same time as the folder. Relevant for all jobs in the SMART folder including jobs that complete ok. Jobs are not automatically removed, but wait for the folder to complete.

DAYSKEEPINNOTOK

Enables you to specify a minimum period to keep the SMART folder (and jobs) in the Active Jobs database after the folder is set to NOT OK.

PARENT_FOLDER

Defines the name of the parent folder to which the job's SMART folder belongs. String. Mandatory.

JOBNAME

Defines the name of the job processing definition.

FILENAME

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

APPLICATION

Defines the name of the application to which the SMART folder belongs. Used as a descriptive name for related groups of SMART folders.

SUB_APPLICATION

Defines the name of the group to which the jobs in the SMART folder are assigned.

CREATED BY

Identifies the Control‑M/EM user who defined the SMART folder.

This argument is used by the Control‑M 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.

RUN_AS

Identifies the user (user ID) associated with the SMART folder. This parameter is used by the Control-M/Server security mechanism.

CRITICAL

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

Valid Values:

  • 0: No

  • 1: Yes

Default: 0

SYSDB

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

Valid Values:

  • 0: Multiple

  • 1: Single

Default: 1

IND_CYCLIC

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

Valid Values:

  • S: Start

  • E: End

APPL_TYPE

Indicates the type of external application, such as SAP or Oracle, where the external application job runs. Mandatory for external application jobs

USE_INSTREAM_JCL

Indicates whether the job should use the INSTREAM_JCL.

Valid Values:

  • Y

  • N

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:

  • Y

  • N

  • D: Runs the unscheduled job as a dummy job

  • B: Bridges the scheduled jobs when there are unscheduled jobs in the folder.

Default: N

INTERVAL

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

CONFIRM

Determines whether the SMART folder must be manually confirmed by the Control‑M/EM user before it runs.

Valid Values:

  • 0: Does not require confirmation.

  • 1: Requires confirmation.

Default: 0

PRIORITY

Indicates Control-M SMART folder priority.

TIMEFROM

Indicates the earliest time for submitting the SMART folder.

TIMETO

Indicates the latest time for submitting the SMART folder.

DUE_OUT

Determines the time that the jobs in the SMART folder are expected to finish.

DOCMEM

Defines the name of the file containing SMART folder documentation.

DOCLIB

Defines the name of the DOCMEM library.

DESCRIPTION

Brief text description of the SMART folder.

CREATION_USER

Defines the name of the user who created the SMART folder.

CREATION_DATE

Determines the date that the SMART folder was created.

CREATION_TIME

Determines the time that the SMART folder was created.

CHANGE_USERID

Defines the name of the user who last modified the SMART folder.

CHANGE_DATE

Date on which the SMART folder was last modified.

CHANGE_TIME

Determines the time that the SMART folder was last modified.

MULTY_Agent

Broadcasts job submission details to all Agents within an Application. The Agent with available resources runs the jobs in the SMART folder.

Valid Values:

  • Y: Runs as a multi-Agent job.

  • N: Does not run as a multi-Agent job.

Default: N

ACTIVE_FROM

(z/OS jobs and SMART folders only) Indicates the start of a period of time that the job or SMART folder can be ordered. Date Format: YYYYMMDD

ACTIVE_TILL

(z/OS jobs and SMART folders only) Indicates the end of a period of time that the job or SMART folder can be ordered. Date Format: YYYYMMDD

JOB

Indicates opening and closing tags of a single job definition. Parameters of the job are listed between the tags. For a complete listing of deffolder parameters, see defjob.

SITE_STANDARD_NAME

Defines the name of the site standard that is applied to the folder and all of its entities. For more information see Site Standards.

Relevant for Control-M Workload Change Manager only.

BUSINESS_PARAMETER_NAME

Defines the name of the Business Parameter name that is applied to the folder and all of its entities. For more information, see Site Standards.

Relevant for Control-M Workload Change Manager only.

VALUE

Defines the value of a customer defined business field.

Relevant for Control-M Workload Change Manager only.

Folder with Two Jobs XML File

In the following example, in the deffolder XML file, specify a folder with two jobs:

Copy 
<FOLDER ENFORCE_VALIDATION="N" TYPE="1" FOLDER_ORDER_METHOD="SYSTEM" 
FOLDER_NAME="Folder#2" 
PLATFORM="UNIX" 
VERSION="900" 
DATACENTER="bmc-user">
<JOB PARENT_FOLDER="Folder#2" 
CYCLIC_TYPE="C" 
CYCLIC_TOLERANCE="3" 
CYCLIC_INTERVAL_SEQUENCE="+5M" 
USE_INSTREAM_JCL="N" 
ACTIVE_TILL="20170226" 
ACTIVE_FROM="20170201" 
MULTY_Agent="N" 
APPL_TYPE="OS" 
TIMEZONE="GMT" 
RULE_BASED_CALENDAR_RELATIONSHIP="O" 
IND_CYCLIC="S" 
SYSDB="1" 
SHIFTNUM="+00" 
SHIFT="Next Day" 
DAYS_AND_OR="O" 
DEC="1" NOV="1" OCT="1" SEP="1" AUG="1" JUL="1" JUN="1" MAY="1" APR="1" MAR="1" FEB="1" JAN="1" 
DAYS="ALL" 
MAXRUNS="0" 
MAXDAYS="0" 
AUTOARCH="1" 
MAXRERUN="1" 
MAXWAIT="98" 
RETRO="1" 
CONFCAL="Calendar1" 
CONFIRM="0" 
CMDLINE="echo_33" 
INTERVAL="00001M" 
CYCLIC="1" 
TASKTYPE="Command" 
CRITICAL="0" 
RUN_AS="emuser" 
CREATED_BY="emuser" 
JOBNAME="OS_Job#1"/>
<JOB PARENT_FOLDER="Folder#2" 
CYCLIC_TYPE="C" 
CYCLIC_TOLERANCE="0" 
USE_INSTREAM_JCL="N" 
MULTY_Agent="N" 
APPL_TYPE="OS" 
RULE_BASED_CALENDAR_RELATIONSHIP="O" 
IND_CYCLIC="S" 
SYSDB="1" 
SHIFTNUM="+00" 
SHIFT="Ignore Job" 
DAYS_AND_OR="O" 
DEC="1" NOV="1" OCT="1" SEP="1" AUG="1" JUL="1" JUN="1" MAY="1" APR="1" MAR="1" FEB="1" JAN="1" 
DAYS="ALL" 
MAXRUNS="0" 
MAXDAYS="0" 
AUTOARCH="1" 
MAXRERUN="0" 
MAXWAIT="0" 
RETRO="0" 
CONFIRM="0" 
CMDLINE="echo_30" 
INTERVAL="00001M" 
CYCLIC="0" 
TASKTYPE="Command" 
CRITICAL="0" 
RUN_AS="emuser" 
CREATED_BY="emuser" 
JOBNAME="OS_Job#3"/>
</FOLDER>
</DEFTABLE>

SMART folder with One Job XML File

In the following example, in the deffolder XML file, define a SMART folder with one job:

Copy 
<SMART_FOLDER ENFORCE_VALIDATION="N" 
TYPE="2" REAL_FOLDER_ID="0" FOLDER_ORDER_METHOD="SYSTEM" 
FOLDER_NAME="EX_Monthly" PLATFORM="MPM" VERSION="900" 
DATACENTER="vw-tlv-idd-dv03" 
DAYSKEEPINNOTOK="5" REMOVEATONCE="Y" 
PARENT_FOLDER="EX_Monthly" 
CYCLIC_TYPE="C" CYCLIC_TOLERANCE="0" USE_INSTREAM_JCL="N" 
APPL_TYPE="OS" IND_CYCLIC="S" ADJUST_COND="N" SYSDB="1" 
SHIFT="Ignore Job" DAYS_AND_OR="O" 
DEC="1" NOV="1" OCT="1" SEP="1" AUG="1" JUL="1" JUN="1" MAY="1" 
APR="1" MAR="1" FEB="1" JAN="1" DAYS="ALL" 
MAXRUNS="0" MAXDAYS="0" AUTOARCH="1" MAXRERUN="0" MAXWAIT="5" 
RETRO="0" CONFIRM="0" INTERVAL="00001M" CYCLIC="0" 
TASKTYPE="SMART Table" 
CRITICAL="0" 
RUN_AS="emuser" 
CREATED_BY="emuser" 
DESCRIPTION="Monthly expenses" 
JOBNAME="EX_Monthly" 
SUB_APPLICATION="Global" 
APPLICATION="Control-M_Housekeeping" JOBISN="0">
<JOB PARENT_FOLDER="EX_Monthly" 
CYCLIC_TYPE="C" CYCLIC_TOLERANCE="0" USE_INSTREAM_JCL="N" 
APPL_TYPE="OS" IND_CYCLIC="S" SYSDB="0" SHIFT="Ignore Job" 
DAYS_AND_OR="O" 
DEC="1" NOV="1" OCT="1" SEP="1" AUG="1" JUL="1" JUN="1" MAY="1" 
APR="1" MAR="1" FEB="1" JAN="1" DAYS="1" 
MAXRUNS="0" MAXDAYS="0" AUTOARCH="0" MAXRERUN="0" MAXWAIT="0" 
RETRO="0" CONFIRM="0" INTERVAL="00000M" CYCLIC="0" 
TASKTYPE="Job" CRITICAL="0" RUN_AS="emuser" CREATED_BY="emuser" 
DESCRIPTION="Calculate the salaries and taxes per employee" 
JOBNAME="CalcSalaries" 
SUB_APPLICATION="Global" APPLICATION="Control-M_Housekeeping" 
JOBISN="0" MULTY_Agent="N" RULE_BASED_CALENDAR_RELATIONSHIP="O" 
CREATION_TIME="135959" CREATION_DATE="20060315" CREATION_USER="emuser" 
PAR="%%HOSTID:\Output\CheckPrintingOutput.txt" 
OPTION="Copy" SHIFTNUM="+00" TIMETO="0300" TIMEFROM="0100" 
MEMLIB="C:\Program Files\BMC Software\CONTROL-M EM 9.0.00\Default\
Samples" DOCMEM="CalcSalaries.txt" 
DOCLIB="C:\Program Files\BMC Software\CONTROL-M EM 9.0.00\Default\
Samples" MEMNAME="CalcSalaries.bat">
<SHOUT MESSAGE="Pay checks can now be printed." DEST="print@acc.com" 
URGENCY="V" WHEN="OK"/>
<INCOND AND_OR="A" ODATE="ODAT" NAME="EX_TimeSheetsSubmitted"/>
<OUTCOND ODATE="ODAT" NAME="EX_CalcSalariesOK" SIGN="+"/>
</JOB>
<RULE_BASED_CALENDAR SHIFT="Ignore Job" DAYS_AND_OR="O" DEC="1" 
NOV="1" OCT="1" SEP="1" AUG="1" JUL="1" JUN="1" MAY="1" APR="1" 
MAR="1" FEB="1" JAN="1" DAYS="ALL" MAXWAIT="00" RETRO="0" 
NAME="EVERYDAY" LEVEL="N"/>
</SMART_FOLDER>

Control-M Workload Change Manager XML file

The following example describes the Control-M Workload Change Manager for the deffolder utility input file.

Copy 
<DEFTABLE xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="Folder.xsd">
<FOLDER DATACENTER="vw-tlv-em-dv131"
VERSION="800"
PLATFORM="UNIX"
FOLDER_NAME="rt"
FOLDER_ORDER_METHOD="SYSTEM" REAL_FOLDER_ID="153" TYPE="1"
ENFORCE_VALIDATION="N" SITE_STANDARD_NAME="st_acc">
<JOB JOBISN="1"
JOBNAME="OS_Job#1"
CREATED_BY="emuser"
RUN_AS="a"
CRITICAL="0"
TASKTYPE="Command"
CYCLIC="0"
INTERVAL="00001M"
CMDLINE="a"
CONFIRM="0"
RETRO="0"
MAXWAIT="0"
MAXRERUN="0"
AUTOARCH="1"
MAXDAYS="0"
MAXRUNS="0"
DAYS="ALL"
JAN="1"
FEB="1"
MAR="1"
APR="1"
MAY="1"
JUN="1"
JUL="1"
AUG="1"
SEP="1"
OCT="1"
NOV="1"
DEC="1"
DAYS_AND_OR="O"
SHIFT="Ignore Job"
SHIFTNUM="+00"
SYSDB="1"
IND_CYCLIC="S"
CREATION_USER="emuser"
CREATION_DATE="20130728"
CREATION_TIME="215511"
RULE_BASED_CALENDAR_RELATIONSHIP="O"
APPL_TYPE="OS"
MULTY_Agent="N"
USE_INSTREAM_JCL="N"
VERSION_OPCODE="N"
IS_CURRENT_VERSION="Y"
VERSION_SERIAL="1"
VERSION_HOST="BMC-HSD2GV1"
CYCLIC_TOLERANCE="0"
CYCLIC_TYPE="C"
PARENT_FOLDER="rt" />
<ADDITIONAL_FOLDER_DETAILS>
<BUSINESS_PARAMETER NAME="Dept" VALUE="Finance" />
</ADDITIONAL_FOLDER_DETAILS>
</FOLDER>
</DEFTABLE>