ctmcreate

The ctmcreate utility is an API that enables a specific job and/or SMART folder or Sub Folder to be inserted directly into the Active Jobs database. The function performed by this utility is equivalent to the Force function. 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, as described in 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 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. From an Agent, type the following command:

   Copy

   ctmcreate
   -TASKTYPE          <JOB|EXTERNAL|DETACHED|COMMAND|DUMMY|FOLDER|SUBFOLDER>
     [ -SUB_APPLICATION           <sub_application name> ]
     [ -APPLICATION     <applic name> ]
     [ -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> ]
     [ -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>] ]

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

  The -domail parameter has the following syntax:
  -domail <destination> <cc> <severity> <subject> <message>

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

  domail [email protected] "" R "subject line" "My message"

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