ctmcreate

The ctmcreate utility is an API that enables a specific purpose job and/or SMART folder or Sub Folder to be inserted directly into the Active Jobs database. The job and/or SMART folder or Sub Folder does not have to be defined in the Control‑M/Server database. The function performed by this utility is equivalent to the Force function in Control‑M/EM. To run the ctmcreate utility, see Running the ctmcreate Utility.

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

ctmcreate -input_file <fullPathFileName>

The referenced file contains all the required parameters. Most of the parameters are described in Control-M Parameters and ctmcreate Parameters.

For more information on syntax rules, see ctmcreate Syntax Rules.

You can create a job within the given Folder or Sub Folder name. The ctmcreate utility can be used to create a specific purpose (non-permanent) folder that is not defined in the Control-M/Server database by specifying:

-TASKTYPE FOLDER|SUBFOLDER -folder <folderName|folderPath>

Running the ctmcreate Utility

This procedure describes how to run the ctmcreate utility, which enables you to insert a specific purpose job directly into the Active Jobs 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

   ctmcreate
   -TASKTYPE          <JOB|EXTERNAL|DETACHED|COMMAND|DUMMY|FOLDER|SUBFOLDER>
     [ -SUB_APPLICATION           <sub_application name> ]
     [ -APPLICATION     <applic name> ]
     [ -DEBUG           <debug level 0-5> ]
     [ -QUIET  ]
     [ -FOLDER_ORD       <Active or Sub folder orderno|ALONE|LAST> ]
     [ -ADJUST_COND     Y|N|B]
     [ -MULTIAgent      Y|N ]
     [ -HOSTGRP         <name> ]
     [ -MEMLIB          <path> ]
     [ -MEMNAME         <filename> ]
     [ -CMDLINE         <string> ]
     [ -EMBEDDED_SCRIPT <file name> ]
     [ -JOBNAME         <name> ]
     [ -FOLDER           <name> ]
     [ -RUN_AS           <username> ]
     [ -CREATED_BY          <username> ]
     [ -ODATE           <date>|ODAT ]
     [ -ODATE_OPTION    VALUE_DATE|RUN_DATE ]
     [ -MAXRERUN        <value> ]
     [ -TIMEZONE        <xxx> ]
     [ -TIMEFROM        <earliest submission time> ]
     [ -TIMEUNTIL       <latest  submission time> | '>' ]
     [ -PRIORITY        <job priority> ]
     [ -CRITICAL        Y|N ]
     [ -CYCLIC          Y|N ]
     [ -CYCLIC_TYPE     INTERVAL|INTERVAL_SEQUENCE|SPECIFIC_TIMES ]
     [ -SPECIFIC_TIMES  <specific times string (HHMM,HHMM)> ]
     [ -INTERVAL_SEQUENCE  <interval sequence string e.g(+1H,+2M)> ]
     [ -TOLERANCE    <maximum delay allowed (minutes)> ]
     [ -CONFIRM         Y|N ]
     [ -APPLTYPE        <Agent_application> ]
     [ -APPLVER         <application version> ]
     [ -CMVER           <CM version> ]
     [ -APPLFORM        <application form> ]
     [ -INTERVAL        <45d(days) | 1080h(hours) | 64800m (minutes)> ]
     [ -INTERVALFROM    START | END | TARGET ]
     [ -OVERRIDE_PATH         <alternative directory> ]
     [ -MAXWAIT         <days> ]
     [ -DESCRIPTION     <string> ]
     [ -DOCMEM          <filename> ]
     [ -DOCLIB          <directory name> ]
     [ -INCOND          <condition> <dateref>|ODAT  AND|OR ]
     [ -OUTCOND         <condition> <dateref>|ODAT  ADD|DEL ]
     [ -VARIABLE        <varname> <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 ]
         [ -DOSHOUT    <destination> <urgency R|U|V> <message> ]
         [ -DOCOND     <condname> <dateref>|ODAT  ADD|DEL ]
         [ -DOVARIABLE <varname> <expression> ]
         [ -DOFORCEJOB <foldername> <jobname> <odate>|ODAT[-UNIQUE_FLOW Y|N]]
         [ -DOOUTPUT    RELEASE|DELETE|COPY|MOVE [<parameter>] ] ]
         [ -DOSTOPCYCLIC ]
         [ -DOMAIL <destination> <cc> <urgency R|U|V> <subject> <message> [<attach output>] ]
         [ -DOREMEDY <summary> <description> <urgency L|M|H|U|C>

ctmcreate Parameters

The following table describes ctmcreate utility parameters:

ctmcreate Syntax Rules

The following rules apply when using this utility:

• More than one parameter can be specified on a line.

• The odate parameter specifies the date to use as the job’s scheduling date. Specify a date in yyyymmdd format, or specify ODAT to accept the ControlM system date.

• The %%NEXT, %%$NEXT, %%PREV, and %%$PREV variables cannot be specified for the ctmcreate utility. These variables refer to the next or previous scheduling date and are not relevant for a utility that places jobs directly in Active Jobs.

• The length of the command line, after decoding, must not exceed 999 characters.

• Although most parameters are optional, certain parameters are required depending on the value specified for tasktype.

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

• All parameter fields (as specified in the syntax) must contain values. If no value is required, specify a null string "" 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.

• For more information, see information about setting Control-M/Server e-mail configuration parameters in Email parameters.

• JOB and DETACHED require file name and file path parameters.

• COMMAND requires the cmdline parameter.

• Strings containing blanks must be enclosed in quotation (for example, cmdline "ctmudlst list payroll").

• A UNIX metasymbol (that must be enclosed in quotation marks) appearing 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.

• A parameter requiring more than one entry can be repeated as many times as necessary (for example, if a job must wait for several prerequisite conditions, specify a separate incond parameter for each prerequisite condition).

The following special characters are disabled when they occur in prerequisite condition names: ( ) | [blanks]

• An on parameter must be followed by at least one do... parameter. do... parameters are dependent upon the last on parameter preceding them. Normally, when a -dorerun parameter is implemented, the current run of the job ends with NOTOK status. To ensure that the job will have OK status even though it is rerun, specify a -do ok parameter immediately after the -dorerun parameter.

• The -dorerun parameter cannot be specified for a cyclic job.

• The order of the parameters does not affect the outcome of the job, with the exception of on and do... parameters.

• When using doforcejob to force an entire folder, <job name> must be specified as a blank enclosed in quotation marks (that is, " ").

• When the ctmcreate utility is invoked from a script, to use the **** option for a incond date parameter, specify the parameter as \"****\"

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

• A maximum of 99 prerequisite conditions can be specified for docond parameters.

  -incond pk_oly_ok "****"

• When the UNIX symbol ~ is used in parameter filepath, -override path, or doclib to represent the user’s home directory, the entire parameter should be enclosed in double quotation marks. The quotation marks ensure that the ~ symbol will be translated by the Agent before submission, and not by the server before transmission to the Agent computer.

  -file_path "~/controlm/scripts/"

ctmcreate - Create a Job in Active Jobs (Simple) Example

The following command contains the minimum parameters required to create a job in Active Jobs:

ctmcreate -TASKTYPE command -subapplication em\
        -application test -cmdline "ls -l /etc/passwd"

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

ctmcreate -input_file ~<controlm_owner>/ctm_server/data/ctmcreate_delfr.txt

The referenced file contains the following lines:

-tasktype command

-subapplication em

-application test

-cmdline "ls -l /etc/passwd"

ctmcreate - Create a Job in Active Jobs (Advanced) Example

The following command includes examples of most of the parameters that can be used to create a job in Active Jobs:

ctmcreate  -TASKTYPE JOB \
-cyclic N \
 -description "Daily Summary" \
 -subapplication SUPPLY   -application SUPPLIES \
  -file_path /users/ctm_server/  -file_name PROLYPAR  -hostgrp UNIXGRP \
-jobname PROLYPAR \
 -run_as suppman \
 -odate 19981130 \
 -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

ctmcreate - Create an Empty SMART folder

The following command creates an empty SMART folder called myfolder:

ctmcreate -TASKTYPE FOLDER -FOLDER myfolder

The response is:

new ORDER created, orderid:00000b(11) for JOBNAME=myfolder.

The following command creates an empty Sub Folder called mysubfolder within the SMART folder called myfolder:

ctmcreate -TASKTYPE SUBFOLDER -FOLDER myfolder/mysubfolder

The response is:

Attached to the SMART folder 'myfolder': 00000b(11)

new ORDER created, orderid:00000c(12) for JOBNAME=mysubfolder.