Create or update a queue manager connection

Purpose

Creates or updates a queue manager connection. A queue manager connection specifies the connection details for one queue manager.

URI

Use the Eclipse Amlen REST API POST method with the following Eclipse Amlen configuration URI:

http://<admin-endpoint-IP:Port>/ima/v1/configuration/

Object configuration data

Provide QueueManagerConnection object configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json:


{    
  "QueueManagerConnection": {
    "<NameOfQueueManagerConnection>": {
      "QueueManagerName": "string",
      "ConnectionName": "string",
      "ChannelName": "string",
      "SSLCipherSpec": "string",  
      "ChannelUserName": "string",
      "ChannelUserPassword": "string",  
      "MQSSLKey": "string",
      "MQStashPassword": "string",
      "Verify": true|false,
      "Force": true|false,
      "Overwrite": true|false           
     }
   }
}
Where:
NameOfQueueManagerConnection
Required.
Specifies the name of the queue manager connection. After the queue manager connection is created, you cannot change this name.
The name must not have leading or trailing spaces and cannot contain control characters, commas, double quotation marks, backslashes, or equal signs. The first character must not be a number or any of the following special characters:
! # $ % & ' ( ) * + - . / : ; < > ? @
The maximum length of the name is 256 characters.
QueueManagerName
Required if you are creating a queue manager connection.
Specifies the name of the queue manager to connect to.
ConnectionName
Required if you are creating a queue manager connection.
Specifies the connection name of the queue manager to connect to.
The connection name consists of the IP address or host name of the queue manager, and optionally, the port number. If a port number is not specified, the default value of 1414 is used. For multi-instance queue managers, you can specify more than one connection by entering the connection names in a comma-separated list.
For a connection name with a port number, you must specify the port number in parentheses. For example: 192.0.2.0(1414) For a connection name without a port number, do not use parentheses. For example: 192.0.2.0
ChannelName
Required if you are creating a queue manager connection.
Specifies the channel name for the queue manager.
The name that you specify must match the name of the server-connection channel that you defined in IBM® MQ.
SSLCipherSpec
Optional.
Specifies the SSL cipher specification that is used in the connection between Eclipse Amlen and IBM MQ.
The cipher that is specified must match the cipher that is defined in IBM MQ for the queue manager that is used in the queue manager connection.
ChannelUserName
Optional.
Specifies the user name to provide to IBM MQ Connectivity channel authentication.
The maximum length of the name is 1024 characters.
If you specify a channel user name, you must also specify a channel user password.
ChannelUserPassword
Optional.
Specifies the password to provide to IBM MQ Connectivity channel authentication
The maximum length of the password is 256 characters.
You must specify a channel user password if you specify a channel user name.
MQSSLKey
Specifies the name of the key database file.
MQStashPassword
Specifies the name of the password stash file.
Verify: true|false
Specifies whether the queue manager connection is tested with the configuration change without committing the configuration change.
Set this value to true to verify that the configuration that you have entered is valid.
The default value is false which means that the configuration change is committed without first testing the queue manager connection.
Force: true|false
Specifies a forced delete or update of the Queue Manager Connection. This action might cause XA transaction IDs to be orphaned.
Overwrite: true|false
Specifies whether an existing certificate and key are overwritten if they have the same name.
The default value is false which means that an existing certificate and key are not overwritten if they have the same name.

Usage Notes®

  • You must copy the key database file and stash password file to the server before you can apply them to Eclipse Amlen. Copy a file from the local machine to Eclipse Amlen to copy the key database file and stash password file.
  • You can copy only one key database file and one stash password file. If you want to use another file, you must overwrite the existing file.
  • You can edit a queue manager connection only if all the destination mapping rules that are using the queue manager connection are disabled. You can disable a destination mapping rule by using the REST API POST method described in Create or update a destination mapping rule.
  • Ensure that capitalization and double quotation marks are used as shown.

Related REST Administration APIs

Example

Creates a queue manager connection called "MyQMC" by using cURL:

curl -X POST \
   -H 'Content-Type: application/json'  \
   -d  '{ 
         "QueueManagerConnection": {   
           "MyQMC": {
             "QueueManagerName": "QM1",
             "ConnectionName": "192.0.2.0(1415)",
             "ChannelName": "SYSTEM.IMA.SVRCONN",
             "MQSSLKey": "my.kdb",
             "MQStashPassword": "mq.sth"                        
          }
        }
     }
 '  \
http://127.0.0.1:9089/ima/v1/configuration/
An example response to the POST method:

{        
  "Version": "v1",
  "Code": "CWLNA6011",
  "Message": "The requested configuration change has completed successfully."
}