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.

DEFFOLDER

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

SMART_FOLDER

Opening and closing tags of a SMART Folder definition.

If you are using Control-M version 6.4.00 or earlier the parameter SCHED_GROUP will be used in place of SMART_FOLDER.

FOLDER_NAME

Name of the SMART Folder to which the job belongs. String. Mandatory.

• The following SMART Folder parameters must be specified for each folder: DATACENTER
• FOLDER_NAME
• FOLDER_DSN (z/OS only)

SUB_APPLICATION

Name of the group to which the jobs in the SMART Folder are assigned. String. Mandatory.

DATACENTER

Name of the Control-M installation to which the SMART Folder belongs. String. Mandatory.

The following folder parameters must be specified for each folder:

• DATACENTER
• FOLDER_NAME
• FOLDER_DSN (z/OS only)

FOLDER_DSN

Library for the folder. String. Optional.

The following folder parameters must be specified for each folder:

• DATACENTER
• FOLDER_NAME
• FOLDER_DSN (z/OS only)

FOLDER_ORDER_ METHOD

String. Optional.

USED_BY

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

USED_BY_CODE

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

MODIFIED

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

LAST_UPLOAD

Date of the last folder upload. String. Optional.

CHECKSUM

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

FOLDER_ID

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

REAL_FOLDERID

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

JOBNAME

Name of the job processing definition.String. Optional.

MEMNAME

Name of the file that contains the job script. String. Optional.

APPLICATION

Name of the application to which the SMART Folder belongs. Used as a descriptive name for related groups of SMART Folders. String. Mandatory.

RUN_AS

Owner (user ID) associated with the SMART Folder. This parameter is used by the Control-M/Server security mechanism. String. Optional.

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. String. Optional.

CONFIRM

Indicates that the SMART Folder must be manually confirmed by the Control‑M/EM user before it runs. Valid values:

• 0 (No confirmation. Default.)
• 1 (Requires confirmation.)

PRIORITY

Indicates Control-M SMART Folder priority. String. Optional.

TIMEFROM

Indicates the earliest time for submitting the SMART Folder. String. Optional.

TIMETO

Indicates the latest time for submitting the SMART Folder. String. Optional.

DUE_OUT

Time that the jobs in the SMART Folder are expected to finish. String. Optional.

DOCMEM

Name of the file containing SMART Folder documentation. String. Optional.

DOCLIB

Name of the DOCMEM library. String. Optional.

DESCRIPTION

Brief text description of the SMART Folder. String. Optional.

CREATED BY

Control‑M/EM user who defined the SMART Folder. String. Mandatory.

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.

CREATION_USER

Name of the user who created the SMART Folder. String. Optional.

CREATION_DATE

Date on which the SMART Folder was created. String. Optional.

CREATION_TIME

Time at which the SMART Folder was created. String. Optional.

CHANGE_USERID

Name of the user who last modified the SMART Folder. String. Optional.

CHANGE_DATE

Date on which the SMART Folder was last modified. String. Optional.

CHANGE_TIME

Time at which the SMART Folder was last modified. String. Optional.

MULTY_AGENT

If set to Y, job submission details are broadcasted to all agents within an Application Group. The agent with available resources runs the jobs in the SMART Folder. Optional.

Valid values:

• Y - run as a multi-agent job
• N - do not run as a multi-agent job. Default.

ACTIVE_FROM

Indicates the start of a period of time during which the job or SMART Folder can be ordered. [For z/OS jobs and SMART Folders, only.] Optional. Date Format: YYYYMMDD

ACTIVE_TILL

Indicates the end of a period of time during which the job or SMART Folder can be ordered. [For z/OS jobs and SMART Folders, only.] Optional. Date Format: YYYYMMDD

RULE_BASED_CALENDAR

Collection of scheduling criteria organized unit with a unique name. Mandatory.

RULE_BASED_CALENDAR RULE_BASED_CALENDAR_NAME="RULE_BASED_CALENDAR1" DAYS="1,8,15,23" DAYS_AND_OR="AND" WEEKDAYS="wcal_3" DATE="18" DAYSCAL="" CONFCAL="cal_4" RETRO="1" SHIFT="PREVDAY" SHIFTNUM="5" MAXWAIT="5" MAXRUNS="2" JAN="1"

RULE_BASED_CALENDAR_NAME

Unique name of the Rule_Based_Calendar. String. Mandatory.

DAYS

Days of the month on which to order the jobs in the SMART Folder. String. Optional.

DAYS_AND_OR

Indicates the relationship between specified Days values and Weekdays values. Optional. Valid values:

• AND
• OR

WEEKDAYS

Days of the week on which to order the jobs in the SMART Folder. String. Optional.

DATE

Specific dates on which to order the jobs in the SMART Folder. String. mmdd format. String. Optional.

DAYSCAL

Name of a user-defined calendar used to specify a set of days. String. Optional.

CONFCAL

Specifies a calendar that is used to validate all specified days and dates on which to schedule the jobs in the SMART Folder. String. Optional.

RETRO

Indicates whether the jobs in the SMART Folder is scheduled for possible execution after their original scheduling date (odate) has passed. Optional. Applies only to Rule_Based_Calendars. Valid values:

• 0 (No. Default)
• 1 (Yes)

SHIFT

Describes how to shift the scheduling date of the jobs in the SMART Folder. Optional. Valid values:

• IGNOREJOB
• PREVDAY
• NEXTDAY
• NOCONFCAL

SHIFTNUM

Number of days to shift the scheduling date of the jobs in the SMART Folder. String. Optional.

RULE_BASED_CALENDAR
continued

MAXWAIT

Number of extra days (beyond the original scheduling date) that the jobs in the SMART Folder are allowed to remain in the Active Jobs database awaiting execution.

The value of MAXWAIT in the Rule_Based_Calendar is the value of the MAXWAIT for the jobs that use this Rule_Based_Calendar.

Integer. Optional.

MAXRUNS

Maximum number of job runs to retain the SYSDATA archive data set for jobs that ended NOTOK. Subparameter of AUTOARCH. String. Valid values: 000 – 998, or 999 to retain the archived data for all runs. Optional.

JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC

Months when the jobs in the SMART Folder can run. Optional. Valid values:

• 0 (Default)
• 1

TAGs

Collection of scheduling criteria organized unit with a unique name. Mandatory. This parameter is for backward compatibility.

TAG TAG_NAME="tag1" DAYS="1,8,15,23" DAYS_AND_OR="AND" WEEKDAYS="wcal_3" DATE="18" DAYSCAL="" CONFCAL="cal_4" RETRO="1" SHIFT="PREVDAY" SHIFTNUM="5" MAXWAIT="5" MAXRUNS="2" JAN="1"

TAG_NAME

Unique name of the tag. String. Mandatory.

DAYS

Days of the month on which to order the jobs in the SMART Folder. String. Optional.

DAYS_AND_OR

Indicates the relationship between specified Days values and Weekdays values. Optional. Valid values:

• AND
• OR

WEEKDAYS

Days of the week on which to order the jobs in the SMART Folder. String. Optional.

DATE

Specific dates on which to order the jobs in the SMART Folder. String. mmdd format. String. Optional.

DAYSCAL

Name of a user-defined calendar used to specify a set of days. String. Optional.

CONFCAL

Specifies a calendar that is used to validate all specified days and dates on which to schedule the jobs in the SMART Folder. String. Optional.

RETRO

Indicates whether the jobs in the SMART Folder is scheduled for possible execution after their original scheduling date (odate) has passed. Optional. Valid values:

• 0 (No. Default)
• 1 (Yes)

SHIFT

Describes how to shift the scheduling date of the jobs in the SMART Folder. Optional. Valid values:

• IGNOREJOB
• PREVDAY
• NEXTDAY
• NOCONFCAL

SHIFTNUM

Number of days to shift the scheduling date of the jobs in the SMART Folder. String. Optional.

TAGs
continued

MAXWAIT

Number of extra days (beyond the original scheduling date) that the jobs in the SMART Folder are allowed to remain in the Active Jobs database awaiting execution.

The value of MAXWAIT in the tag is the value of the MAXWAIT for the jobs that use this tag.

Integer. Optional.

MAXRUNS

Maximum number of job runs to retain the SYSDATA archive data set for jobs that ended NOTOK. Subparameter of AUTOARCH. String. Valid values: 000 – 998, or 999 to retain the archived data for all runs. Optional.

JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC

Months when the jobs in the SMART Folder can run. Optional. Valid values:

• 0 (Default)
• 1

RULE_BASED_CALENDAR_NAMES

Wrapper for specifying one or more Rule-Based Calendars for the SMART Folder.

RULE_BASED_CALENDAR_NAMES RULE_BASED_CALENDAR_NAME="RULE_BASED_CALENDAR_1"

RULE_BASED_CALENDAR_NAME

String. Optional.

TAG_NAMES

Wrapper for specifying one or more TAGs for the SMART Folder. For backward compatibility. This parameter is for backward compatibility.

TAG_NAMES TAG_NAME="TAG_1"

TAG_NAME

String. Optional.

INCOND

In condition. Optional.

INCOND NAME="Cond1" ODATE="ODAT" AND_OR="AND" OP="("

NAME

Name of the In condition. String. Mandatory. 1 - 255 characters, case-sensitive.

ODATE

Order date of the In condition. String. Mandatory.
Default: ODAT

AND_OR

Relationship between conditions. Valid values:

• AND (default)
• OR

OP

Parentheses indicating parts of the condition that are interpreted first. String. Optional.

OUTCOND

Out condition. Optional.

OUTCOND NAME="Job1" ODATE="ODAT" SIGN="ADD"

NAME

Name of the Out condition. String. Mandatory.
1 - 255 characters, case-sensitive.

ODATE

Order date of the Out condition. String. Mandatory.
Default: ODAT

SIGN

Indicates whether to add or delete the condition. Valid values:

• ADD (default)
• DEL

VARIABLE

Wrapper for the Variable expression. Optional.

VARIABLE EXP="%%PARM1=%%TIME"

EXP

Variable expression. String. Mandatory.

%%PARM1=%%TIME

SHOUT

Wrapper for the Shout message. Optional.

SHOUT WHEN="EXECTIME" DEST="workstation1" URGENCY="R" MESSAGE="Job completed OK." TIME=">10"

WHEN

Condition under which the Shout message is sent. Mandatory. Valid values:

• OK (default)
• NOTOK
• RERUN
• LATESUB
• LATETIME
• EXECTIME

DEST

Recipient of the shout message. String. Mandatory.

Valid values: 1 - 16 characters, case-sensitive.

URGENCY

Indicates the urgency of the Shout message. Mandatory.

Valid values:

• R (regular-default)
• U (urgent)
• V (very urgent)

MESSAGE

Text of the message. String. Mandatory.

Valid values: 1 - 70 characters, spaces allowed.

TIME

Time of the message. String. Mandatory.

ON_SUB-APPLICATION

Folder-processing termination status, for a SMART Folder, that determines whether the accompanying DO statements are performed.

ON_GROUP CODE="OK"

CODE

Indicates whether the DO statements are performed when the SMART Folder ends OK or NOTOK. Mandatory.
Valid values:

• OK
• NOTOK

DO_SUB-APPLICATION

Actions to perform when the ON_GROUP condition is fulfilled.

DO_GROUP ACTION="OK"

ACTION

Mandatory. Valid values:

• OK
• NOTOK

DOVARIABLE

Wrapper for the Variable expression. Optional.

DOVARIABLE EXP="%%PARM1=%%TIME"

EXP

The Variable expression. String. Mandatory.

%%PARM1=%%TIME

DOSHOUT

Shout message wrapper. Optional.

DOSHOUT DEST="Wkstn2" URGENCY="R" MESSAGE="Job5 completed OK"

DEST

Recipient of the Shout message.

String. Mandatory.

Valid values: 1-16 characters, case-sensitive.

URGENCY

Urgency of the Shout message. Valid values:

• R (regular-default)
• U (urgent)
• V (very urgent)

MESSAGE

Text of the Shout message. String. Mandatory.

Valid values: 1 - 70 characters, spaces allowed.

DOFORCEJOB

Forces a specified job when the current SMART Folder is complete. Optional.

DOFORCEJOB DSN="45446" FOLDER_NAME="Folder2" NAME="Job4" ODATE="ODAT"

DSN

Library for the (scheduling) folder [z/OS only]. String. Mandatory.

FOLDER_NAME

Name of the folder to which the job belongs. String. Mandatory. Valid values: 1 - 10 characters.

NAME

Name of the job. String. Mandatory.

ODATE

Original scheduling date for the job. String. Default: ODAT

DOCOND

Specifies prerequisite conditions to be added or deleted. Optional.

DOCOND NAME="Cond1" ODATE="ODAT" SIGN="ADD"

NAME

Condition name. String. Mandatory.

Valid values: 1 - 20 characters, case-sensitive.

ODATE

Condition date. String. Mandatory. Default: ODAT

SIGN

Specifies whether to add or delete the condition. Valid values:

• ADD (default)
• DEL

DO MAIL

Sends mail when the SMART Folder run is complete. Optional.

DOMAIL URGENCY="R" DEST="[email protected]" CC_DEST="[email protected]" SUBJECT="OK" MESSAGE="Task completed OK."

ATTACH_OUTPUT

Specifies at the job level whether the output should be sent as an email attachment.

URGENCY

Urgency of the message. Valid values:

• R (regular - Default)
• U (Urgent)

DEST

Recipient of the message. String. Mandatory.

CC_DEST

Additional recipient of the message. String. Optional.

SUBJECT

Brief text description of the message contents. String. Optional.

MESSAGE

Text of the message. String. Mandatory.

JOB

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