CA API Gateway 9.1

9.4 9.1

MQ Native Queue Properties

When creating or viewing details about MQ native queues, the MQ Native Queue Properties appear. The queue properties are organized across these tabs:
gateway
When creating or viewing details about MQ native queues, the MQ Native Queue Properties appear. The queue properties are organized across these tabs:
  • MQ Connection Properties
  • Inbound Options 
  • Outbound Options
For more information about MQ native queues, see Manage MQ Native Queues.
To access the properties for an MQ native queue
:
  1. Run the Manage MQ Native Queues task.
  2. Select a queue and then click [
    Properties
    ]. You can also click [
    Create
    ] to enter the properties for a new queue. The MQ Native Queue Properties appear.
  3. Configure each tab within the properties as necessary. Refer to the appropriate section below for a complete description of each tab.
  4. Click [
    OK
    ] when done.
Configuring the [MQ Connection Properties] Tab
The [
MQ Connection Properties
] tab is used to set connection properties common to both inbound and outbound queues. Configure this tab as follows:
Setting
Description
Connection name
Enter a name to identify the MQ Native connection. This name will be displayed in the policy window when the queue is selected for routing. The connection name is also displayed in Manage MQ Native Queues.
Enabled
Select this check box to enable the queue.
Clear this check box to disable the queue as follows:
Direction
Select the direction of the queue:
  • Outbound
    : The Gateway routes messages to the queue. Queues registered as 'outbound' can be referenced in a policy workflow inside a  Route via MQ Native Assertion.
    • This queue is a template
      : Configures a template outbound queue, where the queue name and reply queue name are specified when the Route via MQ Native Assertion is configured.
  • Inbound
    : The Gateway monitors and consumes messages
    from
     the queue.
    Advanced users can use the following options to fine tune how message are handled for inbound messages. This requires knowledge of the MQI calls.
    • Open Options:
       Establish a connection to the queue using the options specified here. Enter a value that represents the sum of the constant fields for the MQOPEN API call. The Open options are on a per-connection basis. These options apply only when the Gateway initiates a connection to a MQ Queue/Queue Manager.
      Example:
      You want to use the constant fields MQOO_OUTPUT (16) and MQOO_FAIL_IF_QUIESCING (8192). Add these values together and enter the resulting
      8208
       into the Open Options field.
      If you do not specify Open options here, the Gateway consults the
      mq.listenerInboundOpenOptions
       cluster property. If this cluster property is not defined, then the Gateway uses the defaults from the MqNativeConstants class.
    • Get Message Options:
      Retrieve a message from a local queue using the options specified here. Enter a value that represents the sum of the constant fields for the MQGET API call. 
      Example:
      You want to use the constant fields MQGMO_FAIL_IF_QUIESCING (8192) and MQGMO_NO_SYNCPOINT (4). Add these values together and enter the resulting
      8196
       into the Get Message Options field.
      If you do not specify Get Message options here, the Gateway consults the
      mq.listenerInboundGetMessageOptions
       cluster property. If this cluster property is not defined, then the Gateway uses the defaults from the MqNativeConstants class.
    (1) For a list of the Constant Field Values, see: https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_7.1.0/com.ibm.mq.javadoc.doc/WMQJavaClasses/constant-values.html#com.ibm.mq.constants (2) To configure Open Options and Message Options for
    outbound
     messages, see "Configuring the [Target] Tab" in Route via MQ Native Assertion.
Connection properties
Configure the properties for the connection:
  • Host name
    : Enter the MQ queue end point.
  • Port number
    : Enter the MQ queue end point port number. This value must be between 1 and 65535.
  • Queue manager name
    : Enter the name of the queue manager. This name is displayed on the Manage MQ Native Queues dialog.
  • Channel name
    : Enter the MQ queue channel name. If you are using an SSL connection for the MQ Native queue, be sure to specify an SSL channel name.
Security
Specify any security required to access the queue:
  • [
    Credentials are required to…
    ]: Select this check box if the target MQ server requires login credentials. Clear this check box if authentication is not required.
  • User name
    : If credentials are required, enter the user name.
  • Password
    : If credentials are required, select the stored password to use from the drop-down list.
    Only stored passwords may be used here—you cannot type in a password. To define a stored password, click [
    Manage passwords
    ]. For more information, see Manage Stored Passwords.
  • [
    Enable SSL
    ]: Select this check box to use an SSL connection for the MQ Native connection.
    Enabling SSL requires a matching Cipher Spec for the SSL channel defined on the MQ server. It also requires an SSL channel name in the "Channel Name" field; the default channel name SYSTEM.DEF.SVRCONN cannot be used for SSL connections.
  • Cipher Spec
    : When connecting using SSL, choose the cipher specification to use for the SSL channel.
    Tip:
     If you are unsure of the cipher to use, try the default cipher first.
    Technical Note:
     When the Gateway is configured to work with IBM MQ 8.0, if any "TLS_ECDHE_ECDSA" cipher suite is used (indicated by * below), the IBM MQ 8 server certificate must be encrypted using the ECDSA algorithm. If using the IBM Key Management to generate a certificate, use the SHA512withECDSA algorithm to generate the certificate.
  • [
    Use client authentication
    ]: When connecting using SSL, select this check box to present a certificate to the server, if one is requested. Clear this check box to never present a certificate, even if one is requested. Note that access may be denied in this case.
  • Keystore
    : From the drop-down list, choose the keystore from which to retrieve the certificate. Used only if client certificates are used.
Test Settings
Click this button to test the connection settings. This button is unavailable when any required information is missing on this tab.
Security Zone
Optionally choose a security zone. To remove this entity from a security zone (security role permitting), choose "No security zone".
For more information about security zones, see Understanding Security Zones.
This control is hidden if either: (a) no security zones have been defined, or (b) you do not have Read access to any security zone (regardless of whether you have Read access to entities inside the zones).
Configuring the [Inbound Options] Tab
The [
Inbound Options
] tab is used to configure inbound queues that are monitored by the Gateway. Configure this tab as follows
Setting
Description
Acknowledge Behavior
From the drop-down list, select how the Gateway should acknowledge incoming MQ Native messages:
  • On Take
    : The Gateway sends a reply based on the chosen "Inbound Reply Behavior" when it reads the message from the queue being monitored (this is the "Queue name" from the [
    MQ Connection Properties
    ] tab).
  • On Completion
    : The Gateway sends a reply only after successful execution of the associated service (defined under "Service Resolution" on this tab).
Using "On Completion" acknowledgment increases the reliability of message processing. If a Gateway fails during the processing of a message, that message will remain in the queue and can be processed by another node. (This assumes that a cluster of nodes has been configured. For more information, see Configure a Gateway Cluster.
(1) If you have not configured a failure queue, then messages that consistently fail (for example, a back-end service is non-functional) remain in the queue indefinitely. The Gateway tries to process these messages continually and may get stuck in a loop, unless a failure queue is configured. (2) Do not use the Protect Against Message Replay Assertion in any policy that processes messages from queues that are configured with the "On completion" acknowledgement mode without a specified failure destination.
Inbound Reply Behavior
Select a reply behavior for the inbound queue:
  • Automatic
    : The Gateway sends a reply if the MQReplyTo queue name is specified in the message/header attribute.
  • Do not send replies
    : Never send a reply to any queue.
  • Send reply to specified queue
    : Send replies to a specific queue, overriding any replyToQueueName attribute in the MQ message descriptor (MQMD) attribute in inbound messages. Enter the name of the queue in the adjacent box.
    Reply queue Put Message Options:
     Puts a message to a local queue using the options specified here. Enter a value that represents the sum of the constant fields for the MQPUT API call. 
    Example:
    You want to use the constant fields MQGMO_FAIL_IF_QUIESCING (8192) and MQPMO_NEW_CORREL_ID (128). Add these values together and enter the resulting
    8320
     into the Reply queue Put Message Options field.
    If you do not specify Reply queue Put Message options here, the Gateway consults the
     
    mq.listenerInboundReplyQueuePutMessageOptions
     cluster property. If this cluster property is not defined, then the Gateway uses the defaults from the MqNativeConstants class.
Request/Response Correlation
The inbound Request/Response correlation behavior can be specified if either the "Automatic" or "Send reply to specified queue" option was selected:
  • Copy CorrelationID from Request to Response
    : Choose this option to copy the Correlation ID from the request to the response.
  • Set Response CorrelationID from Request's MessageID
    : Choose this option to use the Message ID from the request as the Correlation ID in the response.
Service Resolution
Select how the service should be resolved:
  • Associate queue with published service (bypass resolution
    ): 
    Select this check box to associate the inbound MQ Native queue with a specific published service, bypassing the normal service resolution logic.
    • Service name
      : If associating with a service, choose the service from the drop-down list.
  • Specify content type
    : Select this check box to override the content type.
    • Use Content Type
      : If overriding the content type, choose the content type to use from the drop-down list. If the content type you need isn't listed, type it directly into the drop-down list.
Send failed requests to the specified queue
Select this check box to route the message to a special queue if the service policy does not successfully complete.
The messages sent to the failure queue are not due to a Gateway failure, but rather from other causes such as routing failure, message content, etc.
If this check box is not selected, then the MQ Native configuration should ensure that messages that could not be processed do not remain in the queue indefinitely.
This option is available only when Acknowledgment Behavior is set to “On Completion”.
  • Failure queue name:
     If sending requests to a failure queue, enter the name of the queue that will receive messages that were not successfully processed.
    • Failure queue Put Message Options:
       Puts a message to a failure queue using the options specified here. Enter a value that represents the sum of the constant fields for the MQPUT API call. 
      Example:
      You want to use the constant fields MQGMO_FAIL_IF_QUIESCING (8192) and MQPMO_NEW_CORREL_ID (128). Add these values together and enter the resulting
      8320
       into the Failure queue Put Message Options field.
      If you do not specify Failure queue Put Message options here, the Gateway consults the
        mq.listenerInboundFailureQueuePutMessageOptions
       cluster property. If this cluster property is not defined, then the Gateway uses the defaults from the MqNativeConstants class.
Specify multiple inbound connections
Select this check box to set the maximum number of concurrent inbound connections permitted. The default is
20
.
Clear this check box restrict concurrency to a single inbound connection with this queue configuration .
The
mq.listenerMaxConcurrentConnections
 cluster property specifies the absolute maximum concurrency and will override any larger value entered here.
Override maximum message size
Select this check box to override the permitted maximum size of the message.
Clear this check box to use the value set in the
io.mqMessageMaxBytes
 cluster property.
  • Restrict messages to:
     Enter the maximum permitted size of the message, in bytes
  • Allow unlimited message size (not recommended):
     Select this option to allow response messages of unlimited size.
Configuring the [Outbound Options] Tab
The [
Outbound Options
] tab is used to configure outbound queues that are referenced in the Route via MQ Native Assertion. Configure this tab as follows
Setting
Description
Outbound Reply Behavior
Specify an outbound reply behavior for the queue:
  • Always use temporary queue
    : Choose this to always create a temporary dynamic queue for each request. Use this temporary queue as the reply queue for outbound requests and listen for a response on this queue.
    • Model queue name
      : Enter an input mask for the temporary dynamic queue name. For example, the model name, SYSTEM.DEFAULT.MODEL.QUEUE might create a temporary dynamic queue named: SYSTEM.DEFAULT.MODEL.QUEUE.4F14B2E020012504.
      The model queue must be a permanent queue created by the MQ administrator (for example, MQQDT_PREDEFINED). 
  • No replies (one way)
    : Choose this to not send a reply or wait for a request on the queue. The response to the requestor will be empty, unless some other assertion fills it in.
  • Wait for Reply on specified queue
    : Choose this to have the Gateway look up the specified queue and then wait on that queue for the response. Enter the name of the queue in the adjacent box.
    If this queue is to be a template, the dynamic properties setting for "Wait for Reply on specified queue" are available only if this outbound reply behavior is set here, and the queue name box is left blank.
    Additionally, select one of the following Request/Response Correlation options:
    • Generate New CorrelationID for Request
      : Choose this to have the Gateway generate a unique ID, set it as the CorrelationID attribute on the outbound request, and then select only messages with the matching CorrelationID value from the reply queue.
    • Expect Receiver to Copy Request MessageID to Response CorrelationID
      : Choose this to send the request message as-is, then select only messages with the CorrelationID attribute matching the outbound request's MessageID attribute from the reply queue.
  • Get Reply Message Options: 
    Retrieve an outbound reply message using the options specified here. Enter a value that represents the sum of the constant fields for the MQGET API call. Does not apply if the Outbound Reply Behavior is set to "No replies (one-way)".
    Example:
    You want to use the constant fields MQGMO_FAIL_IF_QUIESCING (8192) and MQGMO_NO_SYNCPOINT (4). Add these values together and enter the resulting
    8196
    into the Get Reply Message Options field.
    If you do not specify Get Reply Message options here, the Gateway consults the
    mq.listenerOutboundReplyQueueGetMessageOptions
     cluster property. If this cluster property is not defined, then the Gateway uses the defaults from the MqNativeConstants class.
Get Reply Message Options
Select this option to specify a value that represents the value of the option parameter in the MQGMO API call when getting a reply message.
The Get Message options are configured on a per-assertion basis through the Route via MQ Native Assertion. If you do not specify Get Reply Message options, the system defaults built into MQ Native are used. If more than one option is required, add the values together (as per the example under "Open Options above). Do not add the same constant more than once.
If you do not specify Get Reply Message options here, the Gateway consults the
mq.routingGetMessageOptions
cluster property. If this cluster property is not defined, then the Gateway uses the defaults from the MqNativeConstants class.
Override MQ Native Queue Connection Properties
This section lets you set specific values for this particular MQ Native Queue, overriding the system defaults.
  • Maximum active connections: 
    Enter the maximum number of active connections for this MQ Native connection. To not permit any active connections, enter
    0
    . To allow unlimited active connections, enter any negative value.
    Leave this field blank to use the default value shown, as defined by the
    mq.ConnectionPool.maxActive
    cluster property. Entering any value overrides the cluster property.
  • Maximum idle connections:
    Enter the maximum number of idle connections allowed for this MQ Native connection. To not permit any idle connections, enter
    0
    . To allow unlimited idle connections, enter any negative value.
    Leave this field blank to use the default value shown, as defined by the
    mq.ConnectionPool.maxIdle
    cluster property. Entering any value overrides the cluster property.
    For best performance, the maximum idle connections and the maximum active connections should be the same value.
  • Maximum wait time for free connections (ms):
    Enter the maximum time to wait (in milliseconds) for an MQ Native connection to be available. To wait indefinitely, enter
    0
     or a negative value.
    Leave this field blank to use the default value shown, as defined by the
    mq.ConnectionPool.maxWait
    cluster property. Entering any value overrides the cluster property.

Content feedback and comments