Server Configuration

The following API commands enable you to configure a Server:

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 the Configuration domain, 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 
curl -X DELETE -H "x-api-key: $token" "$endpoint/config/server/$server"

config servers::get

The config servers::get command enables you to get a list of Server.

CLI Syntax

Copy 
ctm config servers::get

REST API Syntax

The following example describes the REST API syntax in cURL:

Copy 
curl -H "x-api-key: $token" "$endpoint/config/servers"

Response

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

Copy 
{
   "name": "IN01",
   "host": "myhost",
   "state": "Up",
   "message": "Connected",
   "version": "9.0.21.080"
}

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 Server, which enables you to assign it a descriptive name.

host

Defines the Server hostname.

state

Determines the state of the Server.

Valid Values:

  • Up

  • Down

message

Describes the server status message.

Valid Values:

  • Connected

  • Disconnected

  • An error message.

  • "": No message to display.

version

Defines the 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 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 the Configuration domain, 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=IN01
listname=myList
curl -X POST -H "x-api-key: $token" "$endpoint/config/server/$server/notification/list/$listname/setactive"

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=IN01
curl -X GET -H "x-api-key: $token" "$endpoint/config/server/$server/definiton"

Response

The following example shows the config server:definition::get response for a Distributed self-hosted Control-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 example shows the config server:definition::get response for a Helix Control-M/Server:

Copy 
{
   "name": "IN01",
   "host": "myhost",
   "state": "Up",
   "message": "Connected",
   "version": "9.0.21.080"
}

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

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 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 DayClosed 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 self-hosted 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 self-hosted 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 self-hosted 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 Server: 1025–32767

  • z/OS 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 the Configuration domain, 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:

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 DayClosed 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
curl -X POST -H "x-api-key: $token" -d "@c:\tmp\configFile.json" \
"$endpoint/config/server/define"

config server::desiredState

The config server::desiredState command enables you determine the desired states of the self-hosted 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 self-hosted 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 the Configuration domain, 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
curl -X POST -H "x-api-key: $token" "$endpoint/config/server/$server/desiredState/$state"

config server::disable

The config server::disable command removes the ability to monitor or manage the self-hosted 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 self-hosted Control-M/Server name.

If annotation is enabled for the Configuration Management category in the Configuration domain, 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
curl -X POST -H "x-api-key: $token" "$endpoint/config/server/$server/disable"

config server::enable

The config server::enable command restores the ability to monitor or manage the self-hosted 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 self-hosted Control-M/Server name.

If annotation is enabled for the Configuration Management category in the Configuration domain, 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
curl -X POST -H "x-api-key: $token" "$endpoint/config/server/$server/enable"

config server::pause

The config server::pause command pauses a self-hosted 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 the Configuration domain, 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
curl -X POST -H "x-api-key: $token" "$endpoint/config/server/$server/pause"

config server::resume

The config server::resume command resumes a self-hosted 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 the Configuration domain, 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
curl -X POST -H "x-api-key: $token" "$endpoint/config/server/$server/resume"

config server::update

The config server::update command enables you to edit self-hosted 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 Server: 1025–32767

  • z/OS 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 DayClosed 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 the Configuration domain, 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
curl -X POST -H "x-api-key: $token" -d "@c:\tmp\detailsFile.json" \
"$endpoint/config/server/$server"