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:
gateway92
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 OptionsOutbound Options
For more information about MQ native queues, see Manage MQ Native Queues.
After 9.2 CR4 is installed, MQ Message application data is automatically converted to a format specified by the queue manager. Prior to CR4, no conversion is performed. If you need to disable this functionality in CR4 for whatever reason, set the
io.mqConvertMessageApplicationDataFormat
cluster property to 'false'.
CR4 also lets you force properties of an MQ Message to be returned in the MQRFH2 header when reading a message from a queue. To enable this behavior, set the
io.mqForceReturnPropertiesInMQRFH2Header
cluster property to 'true'.
Contents:
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 the Managing MQ Native Queues dialog box.
Enabled
Select this check box to enable the queue. Clear this check box to disable the queue as follows:
  • Inbound queue
    : The listener will stop listening for messages.
  • Outbound queue
    : Any Route via MQ Native assertion that uses this queue will stop working.
Direction
Select the direction of the queue:
  • Outbound
    : The
    API Gateway
    can send/route messages to the connection. Queues registered as outbound can be referenced in a policy workflow inside a Route via MQ Native assertion.
  • Select the
    This queue is a template
    check box to configure a template outbound queue that allows the queue name and reply queue name to be specified later, when the Route via MQ Native assertion is configured in a policy.
  • Inbound
    : The
    API Gateway
    will consume messages from the connection. Queues registered as inbound will be monitored by the
    API Gateway
    .
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.
  • Queue name
    : Enter a name for the queue. This name is displayed on the Manage MQ Native Queues dialog.
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.
    If you are unsure of the cipher to use, try the default cipher first.
  • [
    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 will be monitored by the
API Gateway
. Configure this tab as follows
Setting
Description
Acknowledge Behavior
From the drop-down list, select how the
API Gateway
should acknowledge incoming MQ Native messages:
  • On Take
    : The
    API Gateway
    will send 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
    API Gateway
    will send 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
API 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
API Gateway
Cluster.
(1) If you have not configured a failure queue, then messages that consistently fail (for example, a backend service is non-functional) will remain in the queue indefinitely. The
API Gateway
will continually try to process these messages and may get stuck in a loop, unless a failure queue is configured. (2) The Protect Against Message Replay assertion should not be used in any policy that will process 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
    : Choose this option to have the
    API Gateway
    send a reply if the MQReplyTo queue name is specified in the message/header attribute.
  • Do not send replies
    : Choose this option to never send a reply to any queue.
  • Send reply to specified queue
    : Choose this option to 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.
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
API 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 will be expected to 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
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 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 can be referenced in a 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 beempty, unless some other assertion fills it in.
  • Wait for Reply on specified queue
    : Choose this to have the
    API 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" will be available only if this outbound reply behavior is set here, and the queue name box is left blank.
Request/Response Correlation
If the Outbound Reply Behavior is "Wait for a Reply on a specified queue", select one of the following options:
  • Generate New CorrelationID for Request
    : Choose this to have the
    API 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.
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 blank to use the value from the
    mq.ConnectionPool.maxActive
    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 blank to use the value from the
    mq.ConnectionPool.maxIdle
    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 blank to use the value from the
    mq.ConnectionPool.maxWait
    cluster property.
For more information about these cluster properties, see Input/Output Cluster Properties.