ctmdefine

The ctmdefine utility is an API that adds a job processing definition to one of the following folders in the database:

• A regular folder.

• A SMART folder.

• A sub-folder.

The ctmdefine utility can be used when converting job scheduling information from other job control components to the Control-M/Server. The function performed by this utility is equivalent to the manual process of creating job processing definitions, as described in Job definition.

The ctmdefine utility can be invoked using the -input_file parameter:

-ctmdefine -input_file <fullPathFileName>

The referenced file contains all the required parameters. Most of the parameters are described in ctmdefine Parameters.

For information about ctmdefine syntax rules, see ctmdefine Syntax Rules.

The ctmdefine utility can also be used to define jobs for specific applications, for example, SAP and Oracle Applications (OAP).

When creating new SMART folders or job processing definitions using this utility, consider the following:

• If the job name specified already exists in a job processing definition in the SMART folder, the new job processing definition does not overwrite the existing one. Both job processing definitions appear in the folder, each with a different internal job number.

• If the SMART folder does not exist, the utility creates it.

• After using this utility to create one or more job processing definitions, download the modified SMART folders to the Control-M/EM database.

• A newly created SMART folder can be assigned an Order Method parameter using Control‑M client after the folder is downloaded to the Control-M/EM database or by using the ctmpsm utility.

• Values for a creation/modification timestamp and the user ID of the user who created or modified the job processing definition are automatically added to the communication protocol between Control‑M/EM and Control-M/Server and are stored in the Control‑M/EM database. These values are initialized by the ctmdefine utility and are sent to Control‑M/EM when the SMART folder is downloaded. When the SMART folder is uploaded, Control‑M/EM sends these values to Control-M/Server.

• When defining a job in a nested folder, a folder path to the intended nested folder must be specified (-FOLDER option). The folder path starts from the outermost folder name and is similar to operating system files and directories path. When a folder name is used and the folder does not exist, a folder is created.

• If you define a new Rule-based calendar 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.

Adding a Job to a Folder Using the ctmdefine Utility

This procedure describes how to run the ctmdefine utility, which enables you to add a job processing definition to a folder, a SMART folder, and a sub-folder in the Control-M/Server database.

Begin

1. Do one of the following:

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

   • Windows: Open a command prompt window where Control-M/Server is installed.

   You can also run this utility in Control-M Agent by navigating to where Control-M/Agent is installed.

2. Type the following command:

   Copy

   ctmdefine
   -FOLDER <name>
   -JOBNAME <name>
   -TASKTYPE <JOB|EXTERNAL|DETACHED|COMMAND|DUMMY>
   -SUB_APPLICATION <sub_application name>
   -APPLICATION <applic name>
   [ -CMDLINE <string> ]
   [ -EMBEDDED_SCRIPT <file name> ]
   [ -MAXRERUN <value> ]
   [ -CRITICAL Y|N ]
   [ -END_FOLDER Y|N ]
   [ -CYCLIC Y|N ]
   [ -CYCLIC_TYPE INTERVAL|INTERVAL_SEQUENCE|SPECIFIC_TIMES ]
   [ -INTERVAL <45d(days) | 1080h(hours) | 64800m (minutes)> ]
   [ -SPECIFIC_TIMES <specific times string (HHMM,HHMM)> ]
   [ -INTERVAL_SEQUENCE <interval sequence string e.g(+1H,+2M)> ]
   [ -TOLERANCE <maximum delay allowed (minutes)> ]
   [ -INTERVALFROM START | END | TARGET ]
   [ -OVERRIDE_PATH <alternative directory> ]
   [ -RELATIONSHIP AND|OR ]
   [ -MAXWAIT <days> ]
   [ -HOSTGRP <name> ]
   [ -FILE_PATH <path> ]
   [ -FILE_NAME <filename> ]
   [ -MULTIAgent Y|N ]
   [ -ADJUST_COND Y|N|B]
   [ -RUN_AS <username> ]
   [ -CREATED BY <username> ]
   [ -DEBUG <debug level 0-5> ]
   [ -QUIET ]
   [ -TIMEZONE <xxx> ]
   [ -TIMEFROM <earliest submission time> ]
   [ -TIMEUNTIL <latest submission time> | '>' ]
   [ -PRIORITY <job priority> ]
   [ -CONFIRM Y|N ]
   [ -TASKCLASS DISTRIBUTION_|DECOLLATION
   [ -APPLTYPE <Agent_application> ]
   [ -APPLVER <application version> ]
   [ -CMVER <CM version> ]
   [ -APPLFORM <application form> ]
   [ -DESCRIPTION <string> ]
   [ -DOCMEM <filename> ]
   [ -DOCLIB <directory name> ]
   [ -INCOND <condition> <dateref>|ODAT AND|OR ]
   [ -OUTCOND <condition> <dateref>|ODAT ADD|DEL ]
   [ -VARIABLE <variable name as %%local, %%\global, %%\\smart or %%\\pool\variable> <expression> ]
   [ -QUANTITATIVE <name> <quantity> ]
   [ -OUTPUT RELEASE|DELETE|COPY|MOVE [<parameter>]]
   [ -CONTROL <name> E|S ]
   [ -SHOUT OK|NOTOK|RERUN|LATESUB|LATETIME|EXECTIME <destination> <urgency R|U|V> <message> [<time>| <#mmm>] ]
   [ -ON <statement> <code>|
   <varname> <operator EQ|NE|GT|GE|LT|LE|IR|NR|LK|NL|IX|NX|SW|EW|CO|NC|MP|NP> <value>
   [ -DOOK ]
   [ -DONOTOK ]
   [ -DORERUN ]
   [ -DOOUTPUT RELEASE|DELETE|COPY|MOVE [<parameter>] ] ]
   [ -DOSTOPCYCLIC ]
   [ -DOSHOUT <destination> <urgency R|U|V> <message> ]
   [ -DOCOND <condname> <dateref>|ODAT ADD|DEL ]
   [ -DOVARIABLE <variable name as %%local, %%\global, %%\\smart or %%\\pool\variable> <expression> ]
   [ -DOFORCEJOB <foldername> <jobname> <odate>|ODAT[-UNIQUE_FLOW Y|N]]
   [ -DOREMOTEFORCEJOB <foldername> <jobname> <odate>|ODAT [-UNIQUE_FLOW Y|N ]]
   [ -ORDERVARIABLE <variable name as %%local, %%\global, %%\\smart or %%\\pool\variable> <expression> ]
   [ -DOMAIL <destination> <cc> <urgency R|U|V> <subject> <message> [<attach output>] ]
   [ -DOREMEDY <summary> <description> <urgency L|M|H|U|C> ]
   [ -CAPTURE INTO <variable name as %%local,%%global,%%\\smart or %%\\pool\variable>
   SEARCH <Search string>
   [ SKIPROWS <Number rows>]
   [ SKIPWORDS <Number words> [DELIMITER <Character delimiter> TAKE <Number words|0 until end>]|SKIPCHARS <Number characters> [TAKE <Number chars|0 until end>]]]
   [ -DAYS <daystr> ]
   [ -WEEKDAYS <weekdaystr> ]
   [ -MONTH ALL|JAN|FEB|MAR|APR|MAY|JUN|JUL|AUG|SEP|OCT|NOV|DEC Y|N ]
   [ -DATE <MMDD> ]
   [ -DATEFROM <YYYYMMDD> ]
   [ -DATEUNTIL <YYYYMMDD> ]
   [ -DAYSCAL <calendar> ]
   [ -WEEKCAL <calendar> ]
   [ -CAL_ANDOR AND|OR ]
   [ -SHIFT [</>/@][+/-]nn ]
   [ -CONFCAL <calendar> ]
   [ -RETRO Y|N ]
   [ -RBC <rule_based_calendar> ]

If you define a new Rule-based calendar 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.

Defining Application-Specific Jobs

The ctmdefine utility can be used to define jobs for specific applications, for example, SAP and Oracle Applications. These jobs are defined by setting the -appltype parameter to, for example, SAP or OAP.

The -file_name and -file_path parameters must also be specified for the ctmdefine utility when defining application-specific jobs.

In addition to these parameters, you can specify application-specific parameters as variables. These variables are described in detail in the SAP and Oracle Applications user guides.

ctmdefine Parameters

The following table describes the debug, quiet, and input_file parameters. All other parameters (for example, cyclic job parameters) are described in Control-M Parameters.

ctmdefine Syntax Rules

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.

• 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.

• 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 ControlM/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, -monthALLN 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>.

• 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.

• To specify this command without a value for the cc field, include a null string in the appropriate location.

• 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 "****"

• 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 the Control-M/Server before transmission to the Agent computer.

• 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.

For more information on the parameters for the ctmdefine utility, see ctmdefine Parameters.

ctmdefine Examples

The following command contains the minimum parameters required to define a job:

ctmdefine -folder cmmnds -jobname cmls13 \
-tasktype command  -sub_application em  -application test \
-date 0101  -cmdline "ls -l /etc/passwd"

You can get the same result by using the -input_file parameter as follows:

ctmdefine -input_file ~<controlm_owner>/ctm_server/data/ctmdefine_cmmnds.txt

The referenced file (ctmdefine_cmmnds.txt) contains the following lines:

-folder cmmnds
-jobname cmls13
-tasktype command 
-sub_application em 
-application test
-date 0101
-cmdline "ls -l \etc\passwd"

The following command includes examples of most of the parameters that be used to define a job:

ctmdefine -tasktype JOB -cyclic N\
-folder djsales -jobname dj102\
-description “Daily Summary"\
-sub_application SUPPLY -application SUPPLIES\
-file_path /users/ctm_server/ -file_name PROLYPAR -nodegrp UNIXGRP\
-run_as suppman\
-month ALL N\
-month MAR Y -month JUN Y -month SEP Y -month DEC Y\
-timeuntil 1800\
-priority AA -critical N\
-confirm Y\
-doclib /users/supply/doc/ -docmem prolypardoc\
-incond pk_oly_ok ODAT AND\
-incond pk_olp_ok ODAT AND\
-outcond pk_oly_ok ODAT DEL\
-outcond pk_olp_ok ODAT DEL\
-outcond pk_olypar ODAT ADD\
-variable %%PARM1 “%%CALCDATE %%ODATE -2"\
-quantitative tape 2 -quantitative cpu 50 \
-output MOVE /test/logs/\
-control disk2 E\
-shout OK oper2 U “Daily summary completed"\
-on “COPY JWINFO_2507” “%COPY-E-OPENIN, error"\
-dooutput MOVE /oper/openerr/\
-on “*” notok\
-dorerun\
-doshout em v “Daily summary failed. Attempting rerun"