The following syntax rules apply for this utility:
More than one parameter can be specified on a line.
Keywords can be written in either uppercase or lowercase, but parameter values are case sensitive.
EXAMPLE: -sub_application ACCGROUP and -SUB_APPLICATION ACCGROUP
specify the same sub application ACCGROUP.
-sub_application accgroup
specifies a different sub application accgroup.
For the -month parameter, specify the first three letters of a month (for example, JAN) or ALL for all months (the default is none). To specify two or more individual months, use a separate -month parameter for each month.
If a single character is specified for the priority parameter, the first character is assumed to be A. For example, priority 1 is interpreted as priority A1.
The length of the command line, after decoding, must not exceed 999 characters.
Although most parameters are listed as optional, certain parameters may be required, depending on the option specified for parameter ‑tasktype.
All task types require the sub application and application parameters.
TASKTYPE JOB and DETACHED require parameters file name and file path.
TASKTYPE COMMAND requires parameter cmdline.
FOLDER requires the RBC (Rule-based calendar) parameters. Each RBC definition is followed by its scheduling parameters. If a Rule-based calendar is defined with the ! character at the beginning of the Rule-based calendar name, the Rule-based calendar is excluded. If this feature is disabled, an error message is displayed that you cannot define a Rule-based calendar with the ! character. For more information, see DefaultCTMExcludeRBC in Control-M/EM general parameters.
EXAMPLE:
-rbc myrbc1 -maxwait 1 -days 0,2,3 -dayscal cal1
Strings containing blanks must be enclosed in quotation marks (for example, ‑cmdline "ctmudlst list payroll").
A UNIX metasymbol (that must be enclosed in quotation marks) in a command line string should be enclosed in single quotation (for example, ‑cmdline "ctmcontb list ‘*’ ").
If a parameter value begins with a $ sign, the operating system will try to replace the value. For example, -jobname $USER will cause the shell to substitute the current user. If a parameter value should contain a $ sign, enclose the value in single quotation marks. For example, -jobname ‘test$’ will set the jobname parameter to test$.
A variable that does not contain a $ sign can be enclosed in single or double quotation marks. A variable that does contain a $ sign should be enclosed in single quotation marks. A variable containing a $ sign cannot be resolved if it is enclosed in double quotation marks.
Condition dates are specified in mmdd format. Time is specified in hhmm format.
On computers that support Disk Clustering, the -hostgrp parameter is required (including either a host group name, or the virtual name of the Control‑M/Agent).
A parameter requiring more than one entry can be repeated as needed:
If a job is dependent upon several prerequisite conditions, specify a separate ‑incond parameter for each prerequisite condition.
If a job can run only in January and July, specify a separate -month parameter for each month. (For example, -month ALL N ‑month JAN Y -month JUL Y.)
If a job should run every month except July, specify -month ALL Y and -month JUL N.
If a job is in a SMART Folder and is scheduled according to the FIRSTDAY and SALARY1 Rule-Based Calendars, specify –RBC FIRSTDAY –RBC SALARY1.
The default for the -month parameter is ALL Y, which means that if you want to define a job that should run only in one specific month, you must first indicate that it should not run on any month. For example: -month ALL N -month NOV Y
An ‑on parameter must be followed by at least one ‑do parameter.
Additional post-processing conditions can be set by using -on <statement> <code>.
EXAMPLE: On statement: *
Code: RUNCOUNT>4
Do Shout: To: Control-M/EM
Text: "Job ran more than four times"
‑do parameters are dependent upon the last ‑on parameter preceding them.
The order of parameters does not affect the outcome of the job, with the exception of ‑on and ‑do... parameters.
All fields of each parameter (as specified in the syntax section) must contain values. If no value is required for a parameter field, a null string "" must be specified in the relevant position in the parameter specification.
EXAMPLE: The -domail parameter has the following syntax:
To specify this command without a value for the cc field, include a null string in the appropriate location.
EXAMPLE: -domail johnsmith@bmc.com "" R "subject line" "My message"
Normally, when a -dorerun parameter is implemented, the current run of the job ends with NOTOK status. To ensure that the job will have an OK status, even though it is rerun, specify a -dook parameter immediately after the -dorerun parameter.
The -dorerun parameter cannot be specified for a cyclic job.
When using ‑doforcejob to force an entire folder, <job name> must be specified as a blank enclosed in quotation marks (that is, " ").
IN condition statements that use complex boolean logic can be specified.
For more information, see the description of the In Condition parameter in Control-M Parameters.
When ctmdefine is invoked from a script: To use the **** option for a ‑incond date parameter, specify this parameter as "****"
EXAMPLE: -incond pk_oly_ok "****"
When the UNIX symbol ~ is used in a ‑memlib, -override path, or -doclib parameter to represent the user’s home directory, the entire parameter should be enclosed in double quotation marks, which ensures that the ~ will be translated by the agent before submission, and not by Control-M/Server before transmission to the agent computer.
EXAMPLE: -memlib "~/controlm/scripts/"
A maximum of 99 prerequisite conditions can be specified for docond parameters.
Condition names using both open and closed square brackets ([ and ]) must be enclosed in quotation marks (for example, "RATE[A1]").
The following special characters are disabled when they occur in prerequisite condition names:
( open parenthesis
) close parenthesis
| vertical bar
space
The -shift parameter has been extended to four characters (xyyy). The first character (x) indicates how to shift scheduling of the job if the original scheduling day of the job is not a working day in the CONFCAL calendar. Valid values are:
"" (Blank) – No shifting occurs. The job is not scheduled. Default.
> – Job scheduling is shifted to the next working day in the CONFCAL calendar. Additional shifting may be performed, depending on the yyy value, described below.
< – Job scheduling is shifted to the previous working day in the CONFCAL calendar. Additional shifting may or may not be performed, depending on the yyy value, described below.
@ – Tentatively schedule the job for the current day, even if the current day is not a working day in the CONFCAL calendar. Additional shifting may or may not be performed, depending on the yyy value, described below.
The remaining three characters (yyy) shift scheduling of the job forward or backward the specified number of working days, as defined in the CONFCAL calendar. Valid values are:
Blank - no shifting occurs
-nn or +nn shifts the job forward or backward nn working days in the CONFCAL calendar. nn can be any value from 0 to 62.
NOTE:
If the result of shifting by yyy days is a day that is not allowed (-n was entered for that day in the DAYS parameter), the job is shifted to the next working day (for a forward shift), or to the previous working day (for a backward shift).
If the original scheduling day of the job is a working day in the CONFCAL calendar, the x value is ignored and the yyy value determines when the job is scheduled.
If the original scheduling day of the job is not a working day in the CONFCAL calendar, job scheduling is shifted according to the x value and then shifted again according to the yyy value (if specified) to determine when the job is scheduled.
If the original scheduling day of the job is not a working day in the CONFCAL calendar, and no value (blank) is specified for the x value, the job is not scheduled, and the yyy value (if specified) is ignored.
Confcal and Shift parameters are applied to a scheduling date only if that date already satisfies the Basic Scheduling criteria as specified in the Days, Months, Dates, and Weekdays parameters.
When a variable that ends with a backslash '\' is used with a ctmdefine command from a Control-M/Agent, it fails. For example, this can occur when a UNC path directory is used in a AFT job (%VARIABLE 'path\directory\'). Due to the way the Control-M/Agent submits the command to the Control-M/Server, it wraps it in double quotes, and when a backslash is used at the end of a variable, the quotes are ignored and cause it to fail. To avoid this, add a space character after the backslash.
For more information on the parameters for the ctmdefine utility, see ctmdefine parameters.
