Server Configuration

The following API commands enable you to configure a Control-M/Server:

config server::add
config server::delete
config servers::get
config server:notification:list::setactive
config server:definition::get
config server::define
config server::desiredState
config server::managed
config server::unmanaged
config server::disable
config server::enable
config server::pause
config server::resume
config server::update

config server::add

The config server::add command enables you to add and define a Control-M/Server on Control-M/EM.

CLI Syntax

To verify the Control-M/Server is up and running, run the config servers::get command to check the status of the Control-M/Server.

Copy

ctm config server::add <host> <ctm> <id> [port]

The following table describes the config server::add command parameters.

Parameter	Description
host	Defines the Control-M/Server hostname.
ctm	Defines the logical name of the Control-M/Server.
id	Defines a unique 3-character ID, such as 999 or NYC, which Control-M/EM uses to identify each Control-M/Server.
port	(Optional) Defines the port number that the Configuration Agent uses to communicate with Control-M/EM, as described in Infrastructure Components. Default: 2369 Valid Range: Distributed Control-M/Server: 1025–32767 MVS Control-M/Server: 1024–65534

If annotation is enabled for the Configuration Management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example describes the REST API syntax in cURL:

Copy

host='hostname'
id=123
ctm=myserver
port=2369

curl -X POST $endpoint/config/server -H 'Authorization: Bearer &token'  
-H 'Content-Type: application/json' -d '{"host": "$host","id": "$id","ctm": "$ctm","port": $port}'

config server::delete

The config server::delete command enables you to delete a Control-M/Server from Control-M/EM.

CLI Syntax

Copy

ctm config server::delete <server>

where server defines the Control-M/Server hostname.

If annotation is enabled for the Configuration Management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example describes the REST API syntax in cURL:

Copy

endpoint=https://<controlm>:8443/automation-api
token=
server=
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -X DELETE -H "$AuthHeader" "$endpoint/config/server/$server"

To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config servers::get

The config servers::get command enables you to get a list of Control-M/Server.

CLI Syntax

Copy

ctm config servers::get

REST API Syntax

The following example describes the REST API syntax in cURL:

Copy

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$endpoint/config/servers"

To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

Response

The following example shows the config servers::get response parameters when the operational state of the Control-M/Server up and connected.

Copy

{
   "name": "controlm",
   "host": "myhost",
   "state": "Up",
   "message": "Connected",
   "version": "9.0.21.000"
}

The following table describes the config servers::get command parameters that are shown in the above response.

Parameter	Description
name	Defines the name of the Control-M/Server, which enables you to assign it a descriptive name.
host	Defines the Control-M/Server hostname.
state	Determines the state of the Control-M/Server. Valid Values: Up Down
message	Describes the Gateway status message as it appears in the Control-M Configuration Manager (CCM). Valid Values: Connected Disconnected An error message. "": No message to display.
version	Defines the Control-M/Server version.
desiredState	Determines one of the following desired states of the Control-M/Server: Up: The Configuration Agent attempts to start up the Control-M/Server when it is down, which enables it to communicate with other components. Down: The Configuration Agent attempts to shut down the Control-M/Server when it is up, which removes its ability to communicate with other components. Recycle: The Configuration Agent attempts to restart the Control-M/Server. Ignore: The Configuration Agent does not attempt to start up or shut down the Control-M/Server.
status	Determines one of the following statuses of the Control-M/Server, as described in desiredState. Up Down Recycle Ignore
OSType	Determines one of the following platforms that this Control-M/Server is installed on: Distributed: Control-M/Server is installed on a UNIX or Windows operating system. z/OS: Control-M/Server is installed on a z/OS mainframe operating system.

config server:notification:list::setactive

The config server:notification:list::setactive command enables you to activate a notification destination list.

CLI Syntax

Copy

ctm config server:notification:list::setactive <server> <listname>

The following table describes the config server:notification:list::setactive command parameters.

Parameter	Description
server	Defines the name of the Control-M/Server, which enables you to assign it a descriptive name.
listname	Defines the name of the notification destination list to activate.

If annotation is enabled for the Configuration Management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example describes the REST API syntax in cURL:

Copy

server=controlm
listname=myList
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -X POST -H "$AuthHeader" "$endpoint/config/server/$server/notification/list/$listname/setactive"

To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config server:definition::get

The config server:definition::get command enables you retrieve details for a specific Control-M/Server.

CLI Syntax

Copy

ctm config server:definition::get <server>

where server defines the Control-M/Server hostname.

REST API Syntax

The following example describes the REST API syntax in cURL:

Copy

server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -X GET -H "$AuthHeader" "$endpoint/config/server/$server/definiton"

To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

Response

The following example shows the config server:definition::get response for a DistributedControl-M/Server.

Copy

{
   "code": "017",
   "name": "controlm",
   "host": "myhost",
   "type": "Distributed",
   "desiredState": "Up",
   "state": "Up",
   "message": "Connected",
   "version": "9.0.21.000",
   "configurationAgentPort": 2369,
   "description": "London Control-M/Server",
   "contact": "Jane Roe",
   "isEnabled": true,
   "isManaged": true,
   "gatewayListenHost": "",
   "gatewayListenPort": "",
   "protocol": "SSL",
   "ctmToEMPort": 2370,
   "timeZone": "Africa/Kinshasa",
   "newDayTime": "",
   "weekStartDay": "Monday",
   "dayLightSavingStartDate": "",
   "dayLightSavingEndDate": ""
}

The following table describes the config server:definition::get details that are shown in the above response.

Parameter	Description
code	Defines a unique 3-character ID, such as 999 or NYC, which Control-M/EM uses to identify each Control-M/Server.
name	Defines the name of the Control-M/Server, which enables you to assign it a descriptive name.
host	Defines the Control-M/Server hostname.
type	Determines one of the following platforms that this Control-M/Server is installed on: Distributed: Control-M/Server is installed on a UNIX or Windows operating system. z/OS: Control-M/Server is installed on a z/OS mainframe operating system.
desiredState	Determines one of the following desired states of the Control-M/Server: Up: Configuration Agent attempts to start up the Control-M/Server when it is down, which enables it to communicate with other components. Down: Configuration Agent attempts to shut down the Control-M/Server when it is up, which removes its ability to communicate with other components. Ignored: Configuration Agent does not attempt to start up or shut down the Control-M/Server.
state	Determines the current state of the Control-M/Server. For the description of the available states, see the desiredState parameter.
message	Displays a message returned by the Control-M/Server.
version	Determines one of the following Control-M/Server versions: 921: Control-M/Server 9.0.21.xxx 920: Control-M/Server 9.0.20.xxx 919:Control-M/Server 9.0.19.xxx
configurationAgentPort	Defines the port number that the Configuration Agent uses to communicate with Control-M/EM, as described in Infrastructure Components. Default: 2369
description	Defines a free-text description of the Control-M/Server.
contact	Defines the name of the contact person who is responsible for the maintenance of this Control-M/Server.
isEnabled	Determines whether you can monitor or manage the Control-M/Server and its components and define new jobs or resources on the Control-M/Server: true false
isManaged	Determines whether the Control-M/Server is managed, which enables you to perform administrative actions on the self-hosted Control-M/Server from Control-M/EM: true false
gatewayListenHost	Defines the ... hostname...
gatewayListenPort	Defines the port number that...
protocol	Determines one of the following protocols that Control-M/Server uses to communicate with Control-M/EM: TCP: A transmission control protocol (TCP) is a basic communications standard that is designed to transfer data between applications and devices. SSL: A secure sockets layer (SSL) is a security protocol that runs on top of a communication protocol, such as TCP, and encrypts data that passes between applications and devices.
ctmToEMPort	Defines the port number that Control-M/Server uses to communicate with Control-M/EM. Default: 2370
timeZone	Determines the time zone where the Control-M/Server is located. For more information, see Time Zones.
newDayTime	Defines when the New Day A Control-M process that begins every day at midnight, adds jobs and folders to the Run Queue for the day that is about to begin, and removes jobs and folders from previous days. procedure begins, as described in New Day Procedure.
weekStartDay	Determines the first day of the business week, as follows: Monday Tuesday Wednesday Thursday Friday Saturday Sunday
dayLightSavingStartDate	Determines the calendar date that Daylight Savings Time begins.
dayLightSavingEndDate	Determines the calendar date that Daylight Savings Time ends.
isUppercaseOnly	Determines whether user input is restricted to uppercase letters only in job attributes.
isControlMRestartInstalled	Determines whether Control-M/Restart is installed.
isControlMAnalyzerInstalled	Determines whether Control-M/Analyzer is installed.
isControlMTapeInstalled	Determines whether Control-M/Tape is installed.

config server::define

The config server:discover command enables you to define a Control-M/Server.

CLI Syntax

ctm config server::define <host> <server> <id> [port] [-f <configuration file>]

The following table describes the config server::define command parameters.

Parameter	Description
host	Defines the Control-M/Server hostname.
server	Defines the logical name of the Control-M/Server.
id	Defines a unique 3-character ID, such as 999 or NYC, which Control-M/EM uses to identify each Control-M/Server.
port	(Optional) Defines the port number that the Configuration Agent uses to communicate with Control-M/EM, as described in Infrastructure Components. Default: 2369 Valid Range: Distributed Control-M/Server: 1025–32767 MVS Control-M/Server: 1024–65534
configuration file	Defines a JSON file that contains additional parameters. This file can also contain the parameters described above.

If annotation is enabled for the Configuration Management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

The following JSON example and table show and describe the additional server parameters that you can include in the configuration file.

Copy

{
  "host": "dba-tlv-wjrtok",
  "name": "Melbourne_1",
  "id": "444",
  "ctmToEMPort": 2369,
  "type": "Distributed",
  "version": "921",
  "description": "Melbourne Control-M/Server 1",
  "contact": "George Miller",
  "statisticsAlg": "Job Name",
  "syncMode": "Update Control-M/Server and Control-M/EM",
  "gatewayDesiredState": "Up",
  "gatewayCheckInterval": "20",
  "gatewayStartupFlags": "",
  "protocol": "SSL",
  "timeZone": "MEL (GMT+10:00)",
  "newDayTime": "+12:00 AM",
  "weekStartDay": "Monday",
  "dayLightSavingStartDate": "10012023",
  "dayLightSavingEndDate": "04072024",
  "isUppercaseOnly": true
}

type	Determines one of the following platforms that this Control-M/Server is installed on: Distributed: Control-M/Server is installed on a UNIX or Windows operating system. z/OS: Control-M/Server is installed on a z/OS mainframe operating system.
version	Determines one of the following Control-M/Server versions: 921: Control-M/Server 9.0.21.xxx 920: Control-M/Server 9.0.20.xxx 919:Control-M/Server 9.0.19.xxx
description	Defines a free-text description of the Control-M/Server.
contact	Defines the name of the contact person who is responsible for the maintenance of this Control-M/Server.
statisticsAlg	Determines one of the following job attributes that is used as the key that collects statistics information: Job Name: Defines the job name on a Control-M/Server. Member Name: Defines the job name on a Control-M for z/OS server. A member is a partition of a partitioned data set (PDS) or partitioned data set extended (PDSE) that contains programs, parts of a program, or data. The settings on the Control-M/Server computer must match these settings.
syncMode	Determines when data is synchronized between the Control-M/Server and Control-M/EM, as follows: No Synchronization: Does not synchronize. To manually synchronize, you can perform any of the following procedures: Downloading the Control-M/Server Data to Control-M/EM Uploading the Control-M/EM Data to All Control-M/Servers Creating a Regular or Relative Calendar Update Control-M/Server Definitions during Check-In: Only synchronizes Workspace and calendar changes with the Control-M/Server when Workspaces are checked in. Update Control-M/Server Only: Only synchronizes changes in Control-M/EM with the Control-M/Server. Changes to this Control-M/Server not synchronized with Control-M/EM. Update Control-M/Server and Control-M/EM: Fully synchronizes all Control-M/EM and Control-M/Server changes with each other.
ctm2EMPort	Defines the port number that Control-M/Server uses to communicate with Control-M/EM. Default: 2370
protocol	Determines one of the following protocols that Control-M/Server uses to communicate with Control-M/EM: TCP: A transmission control protocol (TCP) is a basic communications standard that is designed to transfer data between applications and devices. SSL: A secure sockets layer (SSL) is a security protocol that runs on top of a communication protocol, such as TCP, and encrypts data that passes between applications and devices.
gatewayDesiredState	Determines one of the following desired states of the Control-M/Server: Up: Configuration Agent attempts to start up the Control-M/Server when it is down, which enables it to communicate with other components. Down: Configuration Agent attempts to shut down the Control-M/Server when it is up, which removes its ability to communicate with other components. Ignored: Configuration Agent does not attempt to start up or shut down the Control-M/Server.
gatewayCheckInterval	Determines the number of seconds to wait before Control-M/EM checks the status of the Control-M/Server. Default: 20
gatewayStartupFlags	Defines alternative parameters to deliver via the command line that start up the Control-M/Server. There is no need to change this value unless directed by BMC Software.
timeZone	Determines the time zone where the Control-M/Server is located. For more information, see Time Zones.
newDayTime	Defines when the New Day A Control-M process that begins every day at midnight, adds jobs and folders to the Run Queue for the day that is about to begin, and removes jobs and folders from previous days. procedure begins, as described in New Day Procedure.
weekStartDay	Determines the first day of the business week, as follows: Monday Tuesday Wednesday Thursday Friday Saturday Sunday
dayLightSavingStartDate	Determines the calendar date that Daylight Savings Time begins.
dayLightSavingEndDate	Determines the calendar date that Daylight Savings Time ends.
isUppercaseOnly	Determines whether to restrict user input to uppercase letters only in job attributes. If you select this option, you cannot change it without fixing all the job attributes. true false

REST API Syntax

The following example describes the REST API syntax in cURL:

Copy

server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -X POST -H "$AuthHeader" -d "@c:\tmp\configFile.json" \
"$endpoint/config/server/define"

To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config server::desiredState

The config server::desiredState command enables you determine the desired states of the Control-M/Server.

CLI Syntax

ctm config server::desiredState <server> <state>

The following table describes the config server::desiredState command parameters.

Parameter

Description

server

Defines the Control-M/Server name.

state

Determines one of the following desired states of the Control-M/Server:

Up: The Configuration Agent attempts to start up the Control-M/Server when it is down, which enables it to communicate with other components.
Down: The Configuration Agent attempts to shut down the Control-M/Server when it is up, which removes its ability to communicate with other components.
Recycle: The Configuration Agent attempts to restart the Control-M/Server.
Ignore: The Configuration Agent does not attempt to start up or shut down the Control-M/Server.

If annotation is enabled for the Configuration Management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example describes the REST API syntax in cURL:

Copy

server=controlm
state=Up
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -X POST -H "$AuthHeader" "$endpoint/config/server/$server/desiredState/$state"

To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config server::managed

The config server::managed command manages a Control-M/Server, which enables you to perform administrative actions on the Control-M/Server from Control-M/EM.

CLI Syntax

ctm config server::managed <server> <host> [<port>]

The following table describes the config server::managed command parameters.

Parameter

Description

server

Defines the Control-M/Server name.

host

Defines the Control-M/Server hostname.

port

(Optional) Defines the port number that the Configuration Agent uses to communicate with Control-M/EM, as described in Infrastructure Components.

Default: 2369

Valid Range:

Distributed Control-M/Server: 1025–32767
MVS Control-M/Server: 1024–65534

If annotation is enabled for the Configuration Management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example describes the REST API syntax in cURL:

Copy

server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -X POST -H "$AuthHeader" \
"$endpoint/config/server/$server/managed?host=host1&port=2369"

To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config server::unmanaged

The config server::unmanaged command unmanages a Control-M/Server, which removes the ability to perform administrative actions on the Control-M/Server from Control-M/EM. Jobs definition, scheduling and execution are not affected.

CLI Syntax

ctm config server::unmanaged <server> <host>

The following table describes the config server::unmanaged command parameters.

Parameter	Description
server	Defines the Control-M/Server name.
host	Defines the Control-M/Server hostname.

If annotation is enabled for the Configuration Management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example describes the REST API syntax in cURL:

Copy

server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -X POST -H "$AuthHeader" \
"$endpoint/config/server/$server/unmanaged?host=host1"

To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config server::disable

The config server::disable command removes the ability to monitor or manage the Server and its components, and removes the ability to define new jobs or resources on the Server.

CLI Syntax

ctm config server::disable <server>

where server defines the Control-M/Server name.

If annotation is enabled for the Configuration Management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example describes the REST API syntax in cURL:

Copy

server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -X POST -H "$AuthHeader" "$endpoint/config/server/$server/disable"

To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config server::enable

The config server::enable command restores the ability to monitor or manage the Server and its components, and restores the ability to define new jobs or resources on the Server.

CLI Syntax

ctm config server::enable <server>

where server defines the Control-M/Server name.

If annotation is enabled for the Configuration Management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example describes the REST API syntax in cURL:

Copy

server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -X POST -H "$AuthHeader" "$endpoint/config/server/$server/enable"

To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config server::pause

The config server::pause command pauses a Control-M/Server, which enables you to keep jobs from executing until you resume the Control-M/Server.

CLI Syntax

ctm config server::pause <server>

where server defines the Control-M/Server name.

If annotation is enabled for the Configuration Management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example describes the REST API syntax in cURL:

Copy

server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -X POST -H "$AuthHeader" "$endpoint/config/server/$server/pause"

To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config server::resume

The config server::resume command resumes a Control-M/Server, which enables paused jobs to start executing.

CLI Syntax

ctm config server::resume <server>

where server defines the Control-M/Server name.

If annotation is enabled for the Configuration Management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example describes the REST API syntax in cURL:

Copy

server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -X POST -H "$AuthHeader" "$endpoint/config/server/$server/resume"

To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config server::update

The config server::update command enables you to edit Control-M/Server definitions.

CLI Syntax

ctm config server::update <server> -f <details_file>

The following table describes the config server::update command parameters.

Parameter	Description
server	Defines the Control-M/Server hostname.
details_file	Defines a JSON file that contains the update parameters.

The following table describes the parameters in the details_file.

Parameter	Description
host	Defines the Control-M/Server hostname.
version	Determines one of the following Control-M/Server versions: 921: Control-M/Server 9.0.21.xxx 920: Control-M/Server 9.0.20.xxx 919:Control-M/Server 9.0.19.xxx
configurationAgentPort	(Optional) Defines the port number that the Configuration Agent uses to communicate with Control-M/EM, as described in Infrastructure Components. Default: 2369 Valid Range: Distributed Control-M/Server: 1025–32767 MVS Control-M/Server: 1024–65534
description	Defines a free-text description of the Control-M/Server.
contact	Defines the name of the contact person who is responsible for the maintenance of this Control-M/Server.
gatewayListenHost	Defines the hostname of the gateway component. Gateways handle communication between Control-M/EM Servers (GSR and GCS) and Control-M/Servers.
gatewayListenPort	Defines the port number of the gateway component.
protocol	Determines one of the following protocols that Control-M/Server uses to communicate with Control-M/EM: TCP: A transmission control protocol (TCP) is a basic communications standard that is designed to transfer data between applications and devices. SSL: A secure sockets layer (SSL) is a security protocol that runs on top of a communication protocol, such as TCP, and encrypts data that passes between applications and devices.
ctmToEMPort	Defines the port number that Control-M/Server uses to communicate with Control-M/EM. Default: 2370
timeZone	Determines the time zone where the Control-M/Server is located. For more information, see Time Zones.
newDayTime	Defines when the New Day A Control-M process that begins every day at midnight, adds jobs and folders to the Run Queue for the day that is about to begin, and removes jobs and folders from previous days. procedure begins, as described in New Day Procedure.
weekStartDay	Determines the first day of the business week, as follows: Monday Tuesday Wednesday Thursday Friday Saturday Sunday
dayLightSavingStartDate	Determines the calendar date that Daylight Savings Time begins.
dayLightSavingEndDate	Determines the calendar date that Daylight Savings Time ends.
isUppercaseOnly	Determines whether to restrict user input to uppercase letters only in job attributes. If you select this option, you cannot change it without fixing all the job attributes.
isControlMRestartInstalled	Determines whether Control-M/Restart is installed.
isControlMAnalyzerInstalled	Determines whether Control-M/Analyzer is installed.
isControlMTapeInstalled	Determines whether Control-M/Tape is installed.

If annotation is enabled for the Configuration Management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example describes the REST API syntax in cURL:

Copy

server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -X POST -H "$AuthHeader" -d "@c:\tmp\detailsFile.json" \
"$endpoint/config/server/$server"

To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.