ctmorder

The ctmorder utility orders or forces one or more jobs from a SMART folder in the Control‑M/Server database.

If two jobs with the same name exist in a SMART folder and you use the ctmorder utility to order or force a job with that name, only the first job is added to the Active Jobs database.

When ordering a SMART folder, folder-level Rule-Based Calendars are calculated and joined so that if the scheduling criteria are met, the folder will be ordered. As a result of ordering the folder:

• A row in the Active Jobs database is added for this folder.

• All folder contents must pass the order procedure. Each field in the folder is inspected as follows:

  • For regular jobs, the job scheduling criteria is calculated and either Or (default) or And with folder or Sub Folder-level Rule-Based Calendars associated to it, according to the relationship parameter in the job definition. If the scheduling criteria are satisfied the job is inserted into the Active Jobs database. If the scheduling criteria are not satisfied, the job is ignored.

  • For Sub Folders, Rule-Based Calendars of the Sub Folder are calculated and joined. When * is defined, Rule-Based Calendars of the parent folder are fetched. If the result of the Rule-Based Calendars calculation is satisfied, a row for the Sub Folder is added in the Active Jobs database and the Sub Folder content will be ordered. If the result of the Rule-Based Calendars calculation is not satisfied, the Sub Folder is ignored.

• Ordered SMART folder, jobs and Sub Folders status are set to WAIT_SCHEDULING.

• INTO_FOLDER_ORDERID will be used to force (Ordering Sub Folders will not be valid) a job or Sub Folder into already ordered folder or Sub Folder. The ordered job or Sub Folder should belong to the same folder or Sub Folder of the job or Sub Folder we are ordering into. Force a Sub Folder ALONE will not be applicable, for jobs it will be applicable.

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

ctmorder -input_file <fullPathFileName>

The referenced file contains all the required parameters.

Ordering or Forcing a Job Using the ctmorder Utility

This procedure describes how to order or force one or more jobs from a SMART folder in the Control‑M/Server database using the ctmorder utility.

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 one of the following commands:

   • ctmorder -FOLDER <Folder|SMART folder|Folder Path> -NAME <job name|sub folder name> -ODATE <scheduling date>

     [-FORCE <y|n>]

     [-HOLD <y|n>]

     [-UNIQUE <y|n>]

     [-SEQNO <job sequence number>]

     [-INTO_FOLDER_ORDERID <{SMART folder order id}|LAST|ALONE|NEWF]>

     [-NODUPLICATION]

     [-DEBUG <debug level 0-5> ]

     [-QUIET ]

     [-VARIABLE <varname> <expression> ]

     [-ODATE_OPTION <VALUE_DATE|RUN_DATE>]

     Any parameter that includes a wildcard must be enclosed in double quotation.

   • ctmorder -input_file <fullPathToFileName>

ctmorder Parameters

The following table lists the ctmorder utility parameters:

Parameter	Description
-FOLDER	Defines Either a folder name, SMART folder name, or the path to the folder. This value might contain wild characters within the folder path. Wild characters in the outermost folder name are also valid.
-UNIQUE	Adds a unique suffix to every conditional name. Y: add a unique suffix N: do not add a unique suffix Default: N
-NAME	Defines the job name (or mask) of the job(s) to order or force. You can order a SMART folder, but you cannot order an individual job, or selection of jobs, from a SMART folder. The job name can include the following wildcard characters: *: Represents any number of characters (or none).Specify * by itself to include all jobs in the folder. ?: Represents any single character. $: Represents any single character. Any parameter that includes a wilcard character must be enclosed in double quotation. Whether the *, ?, and $ characters act as wildcards or as ordinary characters in a job name is determined by the presence or absence of a -seqno parameter: The *, ?, and $ characters only acts as wildcards in the -jobname parameter if no -seqno parameter is specified. The *, ?, and $ characters only acts as ordinary characters in the -jobname parameter if a -seqno parameter is specified. In this case, the specified job name must exactly match the name of the job in the indicated sequence, or the job will not be ordered.
-ODATE	Indicates the scheduling date (order date) to be associated with the job(s). Valid values: ODAT: The current working date of the computer on which Control‑M/Server is running. yyyymmdd: A specific working day in yyyymmdd format. Default: ODAT The interpretation of this parameter value depends on the value specified for the -odate_option parameter (described below).
-FORCE	Adds the specified jobs to the Active Jobs database regardless of scheduling criteria. If -force is not specified, jobs are added to the Active Jobs database only if their scheduling criteria are satisfied (known as order). Use -INTO_FOLDER_ORDERID to force a job or Sub Folder into a folder or Sub Folder that has already been ordered. Valid values Y: force the specified jobs N: order the specified jobs Default: N
-HOLD	Places the specified jobs in the Active Jobs database in Hold status. Valid values Y: hold the specified jobs N: do not hold the specified jobs Default: N
-SEQNO	Identifies the row number of the job in the SMART folder. The first job in each SMART folder is numbered 1 and each subsequent job increments the counter by one. If this parameter is not specified, the first job in the specified folder is ordered. Optional. If this parameter is specified, any *, ?, and $ characters in the -jobname parameter are assumed to be ordinary characters rather than wildcards. Therefore: Do not specify a -seqno parameter if you are specifying wildcards in the -jobname parameter. If you are specifying *, ?, or $ characters as ordinary characters (not wildcards) in the -jobname, you must specify the appropriate -seqno parameter (and the specified job name must exactly match the actual job name).
-INTO_FOLDER_ORDERID	Applies only to jobs in a SMART folder. If the folder being ordered is not a SMART folder, this parameter is ignored. SMART folder order ID: Order ID of an existing SMART folder. LAST: Jobs are added to the last ordered instance of their SMART folder in the Active Jobs database. ALONE: Jobs are ordered individually. They are not associated with any SMART folder. NEWF: A new folder is created and the specified jobs are ordered to that SMART folder. Default. The SMART folder order id, last, alone and newt options can only be used when the -force parameter is set to y.
-NODUPLICATION	Allows jobs to be ordered and added to an existing ordered SMART folder only if those jobs have not already been ordered in that instance of the SMART folder. This parameter can be specified only if last or <SMART folder order id> is specified for the -INTO_FOLDER_ORDERID parameter. This parameter is relevant only for jobs in a SMART folder.
-DEBUG	-DEBUG is currently not supported. To set the debug level, run the dbglvl ORD command on the Control-M/Server machine, as follows: dbglvl ORD [0-5]: Activates a debug trace on the order service at the specified level. The order service log is located in ~/ctm_server/log/services/ctm-order-service.log dbglvl UT [0-5]: Activates a debug trace on Control-M Python Client at the specified level. The Control-M Python Client log is located in ~/ctm_server/proclog Activates a debug trace at the specified level. Valid values: 0 – 5 Default: 0 Performance is somewhat slower when operating in debug mode. BMC recommends that you activate debug mode only when requested by Technical Support.
-QUIET	Suppresses display of the utility output. If specified, no information messages are displayed during execution of the command.
-VARIABLE	Adds a variable expression to each job, SMART folder, or SMART folder that is ordered by the utility. For more information, see the Control-M Variable facility. The following information must be specified for each new variable: <varName>: Defines the name of the variable. <expression>: Expresses the value assigned to the variable.
-ODATE_OPTION	Indicates how the specified -odate value should be used. Valid values: value_date: The specified odate is the odate value for the job(s). The jobs should be run during the current working day. If a time zone is specified in a job processing definition, the job is run according to the specified time zone. run_date: Jobs ordered by this run of the ctmorder utility should be run only when the specified odate begins. Default: value_date If the specified odate is the current working day, the job will run as described in value_date above. If the specified odate has not begun, such as due to time zone specifications, then the job will wait in the Active Jobs database (with WAIT_ODAT status) until the start of the specified working day. If the specified odate has already passed, the ctmorder utility will not run and an error message will be displayed.
-input_file	Defines the name and full path of a file containing parameters for the utility. In this file, each parameter and its values (if any) are on a separate line with the same syntax they would have on the command line. Using the -input_file parameter enables you to: Prepare and save files of utility parameters that can be reused. Specify utility input longer than the number of characters allowed in the command line. -input_file ~<controlm_run_as name>/ctm_server/data/ctmorder_parms.txt If neither ORDER nor FORCE is included in the command, the specified jobs are ordered.

ctmorder Examples

The following are examples of ctmorder utility:

• The following command orders jobs named acct_job contained in SMART folder ACCT100. Any jobs placed in the Active Jobs database will have the current Control‑M date as their original scheduling date:

  ctmorder -FOLDER ACCT100 -NAME acct_job -ODATE odat

• The same results can be achieved using the -input_file parameter as follows:

  ctmorder -input_file ~<controlm_run_as name>/ctm_server/data/ctmorder_acct100.txt

  The referenced file contains the following lines:

  -FOLDER ACCT100

  -NAME acct_job

  -ODATE odat

• The following command orders all jobs contained in the SMART folder ACCT100 whose job name begins with ga. Any jobs placed in the Active Jobs database will have the date March 15, 2021 as their original scheduling date:

  ctmorder -FOLDER ACCT100 -NAME "ga*" \
  -ODATE 20210315 -FORCE y

• The following command forces all jobs contained in the ACCT100 Sub Folder. Any jobs placed in the Active Jobs database will have the date December 31, 2021 as their original scheduling date:

  ctmorder -FOLDER ACCT100 -NAME ACCT101 \
  -ODATE 20211231 -FORCE y

• The following command forces the third job contained in the SMART folder ACCT200 whose job name parameter consists of prodyjob. This job is placed in the Active Jobs database and will have the date December 31, 2021 as its original scheduling date. This job is added to a folder whose orderid is B2.

• ctmorder -FOLDER ACCT200 -NAME prodyjob \
  -ODATE 20211231 -FORCE y -SEQNO 3 -INTO_FOLDER_ORDERID B2

• The following command assigns the variable %%PRDNDATE with the value of %%ODATE, and orders every job in the PRODUCTION SMART folder whose job name has a prefix of PRDN. These jobs are placed in the Active Jobs database in a folder and are assigned the date December 31, 2021 as their original scheduling date.

  ctmorder -FOLDER PRODUCTION -NAME "PRDN*" \
  -ODATE 20211231 -ORDER y -INTO_FOLDER_ORDERID newt\

  -VARIABLE %%PRDNDATE %%ODATE

• The following command orders every job in the INVENTORY SMART folder whose job name has a prefix in the range BIN_A1 to BIN_A9. These jobs are placed in the Active Jobs database in a new SMART folder, and are assigned December 31, 2021 as their original scheduling date. The APPLICATION and RUN_AS parameters of these jobs are modified to STOCK_COUNT and STOREMAN, respectively.

  ctmorder -FOLDER INVENTORY -NAME "BIN_A?" \
  -ODATE 20211231 -FORCE n -INTO_FOLDER_ORDERID newt   \
  -VARIABLE %%PRDNDATE %%ODATE  \
  -VARIABLE %%APPLIC STOCK_COUNT  \
  -VARIABLE %%RUN_AS STOREMAN