cli Utility

The Command Line Interface (cli) utility is a batch utility that enables you to perform various operations from a command line for the management of jobs, folders, calendars, and Workload Policies.

The following table lists the operations that you can perform through the cli utility and specifies the cli commands for these operations. The table also lists alternative Automation API commands for these operations.

Operation

cli Commands

Automation API Command

Order and force jobs

  • -JOB_ORDER

  • -JOB_FORCE

  • -JOB_ORDER_INTO

  • -JOB_FORCE_INTO

run order

Order and force folders

  • -FOLDER_ORDER

  • -FOLDER_FORCE

  • -SUB-FOLDER_FORCE_INTO

run order

Upload and download folders

  • -FOLDER_UPLOAD

  • -FOLDER_DOWNLOAD

NA, available through Control-M Web

Upload and download calendars

  • -CAL_UPLOAD

  • -CAL_DOWNLOAD

NA, available through Control-M Web

Delete jobs and folders

  • -JOB_DELETE

  • -MEM_DELETE

  • -FOLDER_DELETE

  • -SUB-FOLDER_DELETE

run job::delete

Activate Workload Policy definitions

-WORKLOAD_ACTIVATE

run workloadpolicy::activate

The cli utility can be used on UNIX and Windows computers. The cli utility is installed automatically on Windows computers during installation of the Control-M/EM Gateway, GUI server, and Control-M Configuration Manager components.

Many of the tasks performed by the cli utility can also be performed using Control‑M client. However, by including a utility command in the command line of a job processing definition, you can run the utility at a predetermined time or under a predetermined set of conditions without being present.

You can make multiple requests in a single operation. Each service requires its own service name and includes all the relevant service parameters that follow it.

cli Parameters

The following table lists the cli utility parameters:

Parameter

Description

<user_name>

Defines the Control-M/EM database owner user name.

<password>

Defines the Control-M/EM database owner user password.

<password file>

Defines a flat file containing an unencrypted user name and password on separate lines in the format:

user=<emUser>
password=<emPass>

<Server Name>

Defines the host name of the workstation running Control-M/EM database Server.

If you need to address a GUI server and multiple GUI servers exist, set this parameter to the logical name of the relevant GUI server.

<timeout in seconds>

Defines the time in seconds that the utility waits for a response. Timeout is used to override the default waiting period of 120 seconds.

Do not use timeout with commands that do not return a response (-JOB_DELETE and ‑MEM_DELETE).

-DDMM

Reverses the Odate format, as described below.

-BY_FORCE

Forces the specified folder or calendar. Use this option during upload only.

-ACTION_REASON

Describes a note saved in the audit report explaining the purpose for performing the action.

-ACTION_NOTE

Describes a note saved in the audit report justifying the performance of the action.

<cmd>

Defines the syntax for additional commands that are available for specifying with the cli utility. For more information, see cli cmd parameters.

<ctm_name>

Defines the Control-M name.

<job_name>

Defines the name of the job.

<folder_name>

Defines the name of the folder.

<sub_folder_name>

Defines the name of sub folder.

<Control-M Calendar>

Defines the name of the Control-M Calendar you want to upload or download.

<Odate>

Indicates the scheduling date to be associated with job. Format: MMDD or YYYYMMDD.

If the -DDMM is specified, <Odate> can be specified as DDMM or DDMMYYYY

<folder>

Defines the folder where the job is ordered or forced.

Valid values:

  • RECENT: Orders/forces a job into the recent folder that was previously ordered

  • NEW: Orders/forces a job into a new folder

  • STANDALONE: Orders/Forces a job as a standalone job

  • <TableID>: Orders/forces a job/subfolder into a specified folder

<Duplication>

Specifies whether to add a job to a folder even if there is already a job with that name in the folder.

if <folder> is RECENT or <TableID>

Valid values

  • N: Do not allow duplication of the job.

  • Y: Allow duplication of the job.

This setting can be used only when RECENT or TableID are selected for folder.

<Wait_Odate>

Determines whether you should wait for the Order date to run the job.

  • In Control-M for z/OS this field is mandatory.

  • In Control-M for Distributed Systems this field is optional.

Valid values:

Y: Wait for Order date to run job.

N: Run the job immediately.

If omitted, the job runs immediately. If not omitted, the only valid value is Wait_Odate, meaning wait for Order date to run the job.

<With_Hold>

Enables you to hold all jobs immediately after they are ordered.

Valid values

  • N: Order/Force the job in a free state.

  • Y or With_Hold: Order/Force the job in a Hold state.

<UNIQUE_FLOW>

Determines if a flow in a folder is ordered uniquely. This is only relevant if you are ordering a single folder created in Control-M/EM version 8.0.00 and above. A unique suffix is added to every condition name.

Valid values:

  • Yes

  • No

<library>

(z/OS only) Defines the name of the library in which the folder is located.

<RBC>

Indicates whether the calendar is a Rule Based Calendar (RBC).

Valid values

  • N: Not an RBC

  • Y: Is an RBC

    Default: N

Ordering a Job Using the cli Utility

The following procedure describes how to order a job using the cli utility. You must have proper security authorization when using the cli utility.

Begin

  1. Do one of the following:

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

    • Windows: Open a command prompt window where Control-M/EM is installed. You do not need to be in the Control-M/EM database directory.

      For Windows client installations, open a command prompt window and navigate to the <EM instance name>\bin directory.

  2. Type one of the following commands:

    • UNIX: emcli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> [-T <timeout in seconds>] [-DDMM] [-BY_FORCE] -JOB_ORDER <CTM_name> <folder_name> <job_name> <Odate> <Wait_Odate> [<With_Hold>] [<library>]

    • Windows: cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> [-T <timeout in seconds>] [-DDMM] [-BY_FORCE] -JOB_ORDER <CTM_name> <folder_name> <job_name> <Odate> <Wait_Odate> [<With_Hold>] [<library>]

    When forcing or ordering a job, ControlM/EM does not check if multiple jobs with the same name exist in the folder.

    For more information about the cli parameters, see cli Parameters.

Forcing a Job Using the cli Utility

The following procedure describe how to force a job using the cli utility. You must have proper security authorization when using the cli utility.

Begin

  1. Do one of the following:

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

    • Windows: Open a command prompt window where Control-M/EM is installed. You do not need to be in the Control-M/EM database directory.

      For Windows client installations, open a command prompt window and navigate to the <EM Instance Name>\bin directory.

  2. Type one of the following commands:

    • UNIX: em cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> [-T <timeout in seconds>] [DDMM] -JOB_FORCE <CTM_name> <folder_name> <job_name> [<Odate>] [<library>]

    • Windows: cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> [-T <timeout in seconds>] [DDMM] -JOB_FORCE <CTM_name> <folder_name> <job_name> [<Odate>] [<library>]

    For more information about the parameters for forcing a job, see cli Parameters.

Ordering a Job into a Folder

The following procedure describes how to order a job into a folder. You must have proper security authorization when using the cli utility.

Begin

  1. Do one of the following:

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

    • Windows: Open a command prompt window where Control-M/EM is installed. You do not need to be in the Control-M/EM database directory.

      For Windows client installations, open a command prompt window and navigate to the <EM Instance Name>\bin directory.

  2. Type the following command:

    cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> [-T <timeout in seconds>] [DDMM] -JOB_ORDER_INTO <CTM_name> <folder_name> <job_name> <folder> [<duplication>] [<Odate>] <Wait_Odate> [<With_Hold>] [<library>]

    For UNIX, add the em prefix before typing cli

    For more information about the cli parameters, see cli Parameters.

Forcing a Job into a Folder

The following procedure describes how to force a job into a folder. You must have proper security authorization when using the cli utility.

Begin

  1. Do one of the following:

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

    • Windows: Open a command prompt window where Control-M/EM is installed. You do not need to be in the Control-M/EM database directory.

      For Windows client installations, open a command prompt window and navigate to the <EM Instance Name>\bin directory.

  2. Type the following command:

    cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> [-T <timeout in seconds>] [DDMM] -JOB_FORCE_INTO <CTM_name> <folder_name> <job_name> <folder> [<duplication>] [<Odate>] [<library>]

    For UNIX, add the em prefix before typing cli

    For more information about the parameters for forcing a job, see cli Parameters.

Uploading and Downloading a Folder Using the cli Utility

This procedure describes a series of commands that enable you to perform various tasks. Sub Folders cannot be uploaded or downloaded independently. You must have proper security authorization when using the cli utility.

Begin

  1. Do one of the following:

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

    • Windows: Open a command prompt window where Control-M/EM is installed. You do not need to be in the Control-M/EM database directory.

      For Windows client installations, open a command prompt window and navigate to the <EM Instance Name>\bin directory.

  2. Do one of the following:

    For UNIX, add the em prefix before typing cli

    • Upload a folder: Type one of the following commands:

      • UNIX: em cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> [-T <timeout in seconds>] -FOLDER_UPLOAD <CTM_name> <folder_name> [<Odat>] [<library>]

      • Windows: cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> [-T <timeout in seconds>] -FOLDER_UPLOAD <CTM_name> <folder_name> [<Odat>] [<library>]

    • Download a folder: Type one of the following commands:

      • UNIX: em cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> [-T <timeout in seconds>] -FOLDER_DOWNLOAD <CTM_name> <folder_name> [<library>]

      • Windows: cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> [-T <timeout in seconds>] -FOLDER_DOWNLOAD <CTM_name> <folder_name> [<library>]

    For more information about the cli parameters, see cli Parameters.

Forcing a Folder Using the cli Utility

This procedure describes how to force a folder. Sub Folders cannot be forced, except into a SMART folder. You must have proper security authorization when using the cli utility.

Begin

  1. Do one of the following:

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

    • Windows: Open a command prompt window where Control-M/EM is installed. You do not need to be in the Control-M/EM database directory.

      For Windows client installations, open a command prompt window and navigate to the <EM Instance Name>\bin directory.

  2. Type one of the following commands:

    • UNIX: em cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> [-T <timeout in seconds>] [DDMM] -FOLDER_FORCE <CTM_name> <folder_name> [<Odate>] [<library>]

    • Windows: cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> [-T <timeout in seconds>] [DDMM] -FOLDER_FORCE <CTM_name> <folder_name> [<Odate>] [<library>]

    For more information about the cli parameters, see cli Parameters.

Uploading and Downloading a Calendar

This procedure describes how to upload and download a calendar using the cli utility. You must have proper security authorization when using the cli utility.

Begin

  1. Do one of the following:

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

    • Windows: Open a command prompt window where Control-M/EM is installed. You do not need to be in the Control-M/EM database directory.

      For Windows client installations, open a command prompt window and navigate to the <EM Instance Name>\bin directory.

  2. To upload a calendar, type the following command:

    • UNIX: em cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> [-T <timeout in seconds>] -CAL_UPLOAD <Control-M Calendar>

    • Windows: cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> [-T <timeout in seconds>] -CAL_UPLOAD <Control-M Calendar>

    For UNIX, add the em prefix before typing cli

  3. To download a calendar, type the following command:

    • UNIX: em cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> [-T <timeout in seconds>] -CAL_DOWNLOAD <Control-M Calendar>

    • Windows: cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> [-T <timeout in seconds>] -CAL_DOWNLOAD <Control-M Calendar>

    For UNIX, add the em prefix before typing cli

    For more information about the cli parameters, see cli Parameters.

Forcing a Sub Folder into a SMART folder

The following procedure describes how to force a Sub Folder into a SMART folder. You must have proper security authorization when using the cli utility.

Begin

  1. Do one of the following:

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

    • Windows: Open a command prompt window where Control-M/EM is installed. You do not need to be in the Control-M/EM database directory.

      For Windows client installations, open a command prompt window and navigate to the <EM Instance Name>\bin directory.

  2. Type one of the following commands:

    • UNIX: em cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> [-T <timeout in seconds>] [DDMM] -SUB-FOLDER_FORCE_INTO <CTM_name> <sub_folder_name> <folder> [<Duplication>]<Odate> <Wait_Odate> [<With_Hold>]

    • Windows: cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> [-T <timeout in seconds>] [DDMM] -SUB-FOLDER_FORCE_INTO <CTM_name> <sub_folder_name> <folder> [<Duplication>]<Odate> <Wait_Odate> [<With_Hold>]

    For more information about the cli parameters, see cli Parameters and Force a Sub Folder into a SMART folder Parameters.

Force a Sub Folder into a SMART folder Parameters

The following table lists the parameters for the force a Sub Folder into a SMART folder commands:

Parameters

Description

folder

  • SMART: Folder that the Sub Folder is forced into.

    Valid values:

    • RECENT: Forces the Sub Folder into the SMART folder that was run most recently.

    • NEW: Creates a new folder

  • smart_folderID: Defines the SMART folder ID.

duplication

Adds a Sub Folder to a SMART folder, even if there is a Sub Folder with that name in the SMART folder.

Valid values:

  • Y: Adds the Sub Folder, if required.

  • N: Does not create a duplicate Sub Folder if a Sub Folder of the same name already exists

This setting can be used only when RECENT or smart_folderID are selected for folder.

Ordering a Folder

This procedure describes how to order a folder using the cli utility. You must have proper security authorization when using the cli utility.

Begin

  1. Do one of the following:

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

    • Windows: Open a command prompt window where Control-M/EM is installed. You do not need to be in the Control-M/EM database directory.

      For Windows client installations, open a command prompt window and navigate to the <EM Instance Name>\bin directory.

  2. Type the following command:

    • UNIX: em cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> [-T <timeout in seconds>] [DDMM] -FOLDER_ORDER <CTM_name> <folder_name> [<Odate>] [<library>]

    • Windows: cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> [-T <timeout in seconds>] [DDMM] -FOLDER_ORDER <CTM_name> <folder_name> [<Odate>] [<library>]

    For more information about the cli parameters, see cli Parameters.

Deleting a Sub Folder

This procedure describes how to delete a Sub Folder using the cli utility, which enables you to delete the Sub Folder from the Control-M/EM database only. Sub folders in the Control-M/Server database are not affected.

Begin

  1. Do one of the following:

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

    • Windows: Open a command prompt window where Control-M/EM is installed. You do not need to be in the Control-M/EM database directory.

      For Windows client installations, open a command prompt window and navigate to the <EM Instance Name>\bin directory.

  2. Type one of the following commands:

    • UNIX: em cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> -SUB-FOLDER_DELETE <CTM_name> <sub_folder_Name>

    • Windows: cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> -SUB-FOLDER_DELETE <CTM_name> <sub_folder_Name>

    Deleting Sub folders using the cli utility deletes all of the Sub Folders contents. If you only want to delete a job use the -JOB_DELETE command.

    For more information about the cli parameters, see cli Parameters.

Deleting a Job Definition by Job Name

The following procedure describes how to delete a job definition using the cli utility. This deletes the job definitions from the Control-M/EM database only. Job definitions in the Control-M/Server database are not affected.

Begin

  1. Do one of the following:

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

    • Windows: Open a command prompt window where Control-M/EM is installed. You do not need to be in the Control-M/EM database directory.

      For Windows client installations, open a command prompt window and navigate to the <EM Instance Name>\bin directory.

  2. Type one of the following commands:

    • UNIX: em cli [[-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> -JOB_DELETE <CTM_name> <folder_name> <job_name> ALL/NONE/NUMBER [<library>]

    • Windows: cli [[-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> -JOB_DELETE <CTM_name> <folder_name> <job_name> ALL/NONE/NUMBER [<library>]

    For more information about the cli parameters, see cli Parameters and Delete a Job Definition Parameters.

Deleting a Job Definition by File Name

The following procedure describes how to delete a job definitions using the cli utility. This deletes the job definitions from the Control-M/EM database only. Job definitions in the Control-M/Server database are not affected.

Begin

  1. Do one of the following:

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

    • Windows: Open a command prompt window where Control-M/EM is installed. You do not need to be in the Control-M/EM database directory.

      For Windows client installations, open a command prompt window and navigate to the <EM Instance Name>\bin directory.

  2. Type one of the following commands:

    • UNIX: cli [[-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> -MEM_DELETE <CTM_name> <folder_name> <mem_name> ALL/NONE/NUMBER [<library>]

    • Windows: cli [[-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> -MEM_DELETE <CTM_name> <folder_name> <mem_name> ALL/NONE/NUMBER [<library>]

    For more information about the cli parameters, see cli Parameters and Delete a Job Definition Parameters.

Delete a Job Definition Parameters

The following table lists the parameters for deleting a job definition commands:

Parameter

Description

mem_name

Indicates the name of the file that contains the job script, or for z/OS jobs, the name of a member that contains one of the following in relation to the job to be executed:

  • The JCL of the job

  • The started task procedure

  • Warning messages

ALL

Deletes all occurrences of the job if there is more than one job with the same name.

NONE

Keeps all jobs if there is more than one job with the same name.

NUMBER

Deletes the job with the specified sequence number of the duplicate job (for example, if 5 is entered, the fifth occurrence of the Job Name is deleted).

library

Required for z/OS job definitions.

Deleting a Folder Definition

The following procedure describes how to delete a folder definition using the cli utility. You can choose whether to delete folder definitions from the Control-M/EM database, Control-M/Server database, or both.

Begin

  1. Do one of the following:

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

    • Windows: Open a command prompt window where Control-M/EM is installed. You do not need to be in the Control-M/EM database directory.

      For Windows client installations, open a command prompt window and navigate to the <EM Instance Name>\bin directory.

  2. Type one of the following commands:

    • UNIX: em cli [[-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> -FOLDER_DELETE <CTM_name> <folder_name> [<library>] Delete/Force/Remote/Local

    • Windows: cli [[-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> -FOLDER_DELETE <CTM_name> <folder_name> [<library>] Delete/Force/Local/Remote

    For more information about the cli parameters, see cli Parameters and Delete a Folder Definition Parameters

Delete a Folder Definition Parameters

The following table lists the parameters for deleting a folder definition command:

Parameter

Description

folder_name

Defines the name of the folder that you want to delete.

Delete

Deletes the folder definition from both the Control-M/EM database and the Control-M/Server database.

Deletion from the Control-M/Server database is not forced if differences are detected in the folder definition between the two databases.

Force

Forces deletion from both the Control-M/EM database and the Control-M/Server database, even if differences are detected in the folder definition between the two databases.

Local

Deletes the folder definition only from the Control-M/EM database.

Remote

Forces deletion of the folder definition only from the Control-M/Server database.

library

Required for z/OS job definitions.

Activating a Workload Policy Definition Using the cli Utility

This procedure describes how to activate a Workload Policy definition using the cli utility, which enforces all the rules of the Workload Policy definition on the associated jobs.

Begin

  1. Do one of the following:

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

    • Windows: Open a command prompt window where Control-M/EM is installed. You do not need to be in the Control-M/EM database directory.

  2. To upload activate a Workload Policy Definition, type one of the following commands:

    • UNIX: em cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> [-T <timeout in seconds>] -WORKLOAD_ACTIVATE <Workload_name> Y/N

    • Windows: cli [-U <user_name> [-P <password>] | -PF <password file>] -H <Server Name> [-T <timeout in seconds>] -WORKLOAD_ACTIVATE <Workload_name> Y/N

    For more information about the cli parameters, see cli Parameters.