Manage MQ Native Queues

 
gateway91
 
The
Manage MQ Native Queues
task is used to configure the
API Gateway
to natively communicate with IBM WebSphere MQ to exchange both inbound and outbound messages.
IBM WebSphere MQ is a widely-deployed message-oriented middleware (MOM) solution that is commonly used in enterprises to integrate disparate systems and enable asynchronous transaction models. Most integrations typically use standards-based protocols such as JMS. However, there may be instances where integration using proprietary channels is preferred. For example, instead of using JMS and JNDI to exchange messages with MQ Native, you can use the native integration.
For information on installing the MQ Native .JAR files, refer to Install the JMS Interface.
Understanding MQ Native Message Size
The maximum size of an MQ Native message is governed by the following two global cluster properties:
  • io.xmlPartMaxBytes
    : This controls the maximum size of any XML message, including MQ messages. By default, this is 2621440 bytes (2.5MB).
  • io.mqMessageMaxBytes
    : This controls the maximum size of MQ Native messages, including the XML and all MIME parts. By default, this is the same as io.xmlPartMaxBytes (2.5MB).
Normally, these two properties would have the same limit. If you need to further restrict the size of MQ Native messages globally, set io
.mqMessageMaxBytes
to a lower value than
io.xmlPartMaxBytes
.
These global limits can be overridden for both inbound MQ native messages and outbound MQ native messages (via the Route via MQ Native assertion).
Working with MQ Native Queues
An inbound queue allows the
API Gateway
 to consume messages from an MQ connection, whereas an outbound queue allows the
API Gateway
 to send/route messages to that connection. Queues must be created in the WebSphere MQ management application before they can be configured in the Policy Manager.
Once the queues are created in the WebSphere MQ management application, you can add, edit, or remove customized message descriptors, properties, and additional headers.
For inbound and outbound MQ Native messages, you can modify the Message Descriptor, Message Properties, and Additional Headers. To customize Message Descriptors, use the Manage Transport Properties/Headers assertion. An MQ Native queue can be edited or deleted at any time. The  will enable such changes within a few seconds.
Header type conversions such as MQRFH to MQRFH2 and vice-versa are supported for configuring the Additional Header and Message Property.
When the Route via MQ Native assertion is configured to “Get from queue”, it will be able to consume a message from an outbound queue.
Outbound MQ Connection Management
The
API Gateway
 will close an outbound MQ connection under any of the following conditions:
  • the connection has been idle for too long (controlled by
    io.mqConnectionCacheMaxIdleTime
    cluster property)
  • the connection is too old (controlled by
    io.mqConnectionCacheMaxAge
    cluster property)
  • there are too many open connections (controlled by
    io.mqConnectionCacheSize
    cluster property)
If many outbound queues are in use, you can improve performance by reducing the idle time and increasing the cache size.
Template Outbound Queues
A template outbound queue is a special type of queue that allows the following properties to be omitted when the queue is created, to be filled in later during policy construction:
Queue name
(MQ Connections Properties tab)
Wait for Reply reply on specified queue name
(Outbound Options tab)
When you omit either of these properties during the queue definition, the policy author can enter the values during policy design in the Route via MQ Native assertion. However if any of the above properties are set in the template queue, they cannot be changed when the template is used in the Route via MQ Native assertion.
To manage MQ Native Queues
:
  1. In the Policy Manager, select
    [Tasks] > Transports > Manage MQ Native Queues
    from the Main Menu (on the browser client, from the Manage menu). The Manage MQ Native Queues dialog appears.
  2. Choose one of the following actions.
    Action
    Description
    Filter list of queues (optional)
    When there are a large number of MQ Native queues, you can filter the list to more easily locate the queue you want:From the drop-down list, select the queue property to filter.
    1. Type a few characters to search on. This text will be matched anywhere within the chosen queue property and is not case sensitive.
    2. Indicate whether to include only Inbound, Outbound, or Both types of queues.
    3. Click [
      Filter
      ]. The list is filtered to display only those queues matching the filter criteria.
    Sort queue list based on column
    By default, the list of queues is sorted in ascending order by Name.
    Click on any column heading to re-sort the table based on that column. The following markers indicate the sorting column:
    • = The table is sorted in ascending alphabetical order based on the indicated column.
    • = The table is sorted in descending alphabetical order based on the indicated column.
    Add a new MQ Native queue
    Click [
    Add
    ] and then configure the properties for the new queue. See MQ Native Queue Properties for details.
    You can also create a new MQ Native queue by clicking [
    New Queue
    ] on the Native MQ Routing Properties dialog.
    Clone an existing MQ Native queue
    Select the queue to clone, then click [
    Clone
    ]. Edit the queue properties as required. See MQ Native Queue Properties for details.
    Modify an existing MQ Native queue
    Select the queue to modify, then click [
    Properties
    ]. Edit the queue properties as necessary. See MQ Native Queue Properties for details.  
    Be sure to test your new settings to ensure the connection is valid.
    Remove an MQ Native queue
    Select the queue to remove and then click [
    Remove
    ]. Click [
    OK
    ] to confirm the deletion.
    Removing a queue only unregisters it from the
    API Gateway
    . The queue still exists in the WebSphere MQ queue management application.
  3. Click [
    Test Settings
    ] to test the connection between the
    API Gateway
     and MQ Native queue. A test is considered successful if the
    API Gateway
     can:   
    • Read from an inbound queue
    • Write to an outbound queue
    • Contact any additional queue specified in the configuration (for example, a Reply-to queue, Failure queue, Wait-for-reply queue)If a connection cannot be established, make a note of the diagnostic information that is displayed, double-check the queue and
      API Gateway
       settings, and then try again. Occasionally, the queue may enter an unstable state and restarting the MQ Queue Manager and its listener could resolve the issue. 
  4. Click [
    Save
    ] to close the MQ Native Queue Properties. When adding a queue, the new queue is registered in the
    API Gateway
     and added to the Known MQ Native Queues table in the Manage MQ Native Queues dialog.
    The [
    Save
    ] button is unavailable if there is information missing in any of the tabs.
  5. Click [
    Close
    ] when done.