+

Search Tips   |   Advanced Search

Mapping destinations to and from IBM MQ queues, topics, and destinations

Service integration messages and IBM MQ messages both contain header fields and properties. Some of these header fields and properties contain destinations or destination properties that provide information about send-to and reply-to destinations, and about destinations in the bus forward and reverse routing paths. Because service integration and IBM MQ have different definitions for destinations, mappings are used to process the destinations and destination properties when messages are converted between service integration format and IBM MQ format.


Destinations and destination properties in the IBM MQ format message

The IBM MQ format message contains the following information related to destinations:

MQXQH RemoteQName

MQXQH RemoteQMgrName

These fields are present in the MQXQH (the IBM MQ Transmission-queue header). The MQXQH is attached to messages only while they travel between IBM MQ queue managers, or between IBM MQ queue managers and service integration buses across an IBM MQ link. Sending and receiving applications cannot access these fields.

The RemoteQName field contains the name of the send-to queue (IBM MQ) or send-to destination (service integration). The RemoteQMgrName field identifies the queue manager or queue-sharing group (IBM MQ) or service integration bus (service integration) where the send-to queue or destination is located. Usually, the RemoteQMgrName field contains the name of the remote queue manager, queue-sharing group, or service integration bus, but it can contain an IBM MQ queue manager alias or a service integration virtual queue manager name. Note that these fields are not used for topics.

The RemoteQName and RemoteQMgrName values can be up to a maximum length of 48 characters, and must conform to IBM MQ naming restrictions.

MQRFH2 jms.Dst (JMSDestination)

This field is present in IBM MQ format JMS messages that include the MQRFH2 header.

The jms.Dst field contains a serialized representation (an IBM MQ URI) of the send-to JMS destination that was set when the application issued send for the message. Refer to the IBM MQ library for more information about the IBM MQ URI format for JMS destinations.

When service integration sends a message that has a forward-routing path to IBM MQ, it adds an ibmRoutingPath attribute to this URI. The ibmRoutingPath value identifies the forward routing path from the service integration message. IBM MQ does not use the forward routing path, but the send-to destination might be in a remote service integration bus that can use the forward routing path.

MQMD ReplyToQ

MQMD ReplyToQMgr

These fields are present in all IBM MQ format messages.

If the sending application specifies a reply-to queue, the ReplyToQ field contains the name of the reply-to queue (IBM MQ) or reply-to destination (service integration), and the ReplyToQMgr field identifies the queue manager or queue-sharing group (IBM MQ) or service integration bus (service integration) where that queue is located. Usually, the ReplyToQMgr field contains the name of the queue manager, queue-sharing group, or service integration bus, but it can contain an IBM MQ queue manager alias or a service integration virtual queue manager name. If the sending application specifies a reply-to topic, or if it does not specify a reply-to destination, these fields contain null values.

The ReplyToQ and ReplyToQMgr values can be up to a maximum length of 48 characters, and must conform to IBM MQ naming restrictions.

MQRFH2 jms.Rto (JMSReplyTo)

This field is present in IBM MQ format JMS messages that include the MQRFH2 header and that specify a reply-to destination. IBM MQ JMS applications usually use this message attribute as the destination for reply messages, but other (non-JMS) IBM MQ applications usually do not use it; they use the MQMD reply-to fields instead.

The jms.Rto field contains a serialized representation (an IBM MQ URI) of the reply-to JMS destination that is set by the sending JMS application. Refer to the IBM MQ library for more information about the IBM MQ URI format for JMS destinations.

When service integration sends a message that has a reverse-routing path to IBM MQ, service integration adds an ibmRoutingPath attribute to this URI. The ibmRoutingPath value identifies the reverse-routing path from the service integration message. When the receiving JMS application sends a reply, IBM MQ includes the routing path information from the reply-to URI in the send-to URI of the reply message so that service integration can use it for routing the reply message.


Destination conversion when service integration converts a message to IBM MQ format

When service integration converts a message to IBM MQ format, it puts the following destination information into the IBM MQ format message:

MQXQH RemoteQName

MQXQH RemoteQMgrName

These fields apply only when service integration is sending the message across an IBM MQ link, and only when the destination is a queue.

Service integration sets these fields based on the resolved send-to destination for the message; that is, if the send-to destination is an alias, service integration uses the target bus and target identifier. Processing is then as follows:

  • If the send-to destination is in an indirectly-connected bus, it stores the destination name (identifier) as the RemoteQName and the bus name as the RemoteQMgrName.

  • If the send-to destination is in the directly-connected bus and the destination name (identifier) is in the form queue@queueManager, it stores the queue name (queue) as the RemoteQName and the queue manager name (queueManager) as the RemoteQMgrName.

  • If the send-to destination is in the directly-connected bus and the destination name (identifier) is not in the form queue@queueManager, it stores the destination name as the RemoteQName and the bus name as the RemoteQMgrName.

If the send-to destination is in an indirectly-attached service integration bus and its destination name does not comply with IBM MQ naming restrictions, we must define an alias destination with a compliant name; the sending application must use the compliant (alias) name. In this case, we must define the alias destination in the remote (indirectly-attached) bus, not the local bus.

If the send-to destination is in an indirectly-attached service integration bus and its bus name does not comply with IBM MQ naming restrictions, there must be a virtual queue manager name for the indirectly-attached bus. In this case, the local bus must define the indirectly-attached bus with its virtual queue manager name, not its bus name.

For more information about mapping service integration bus names that do not comply with IBM MQ naming restrictions, see How to address bus destinations and IBM MQ queues.

MQRFH2 jms.Dst (JMSDestination)

If the IBM MQ format message includes the MQRFH2 header, service integration serializes the JMSDestination header field into an IBM MQ URI and stores it in the JMSDestination field in the IBM MQ message. If the message has a forward-routing path, service integration includes that in the URI as the ibmRoutingPath attribute.

MQMD ReplyToQ

MQMD ReplyToQMgr

The sending JMS application can set these fields directly using the provider-specific JMS message properties JMS_IBM_MQMD_ReplyToQ and JMS_IBM_MQMD_ReplyToQMgr. If the sending application does not do this, service integration sets the properties if (and only if) the message has a reply-to destination and that destination is a queue.

Service integration sets these fields based on the unresolved reply-to destination for the message; that is, if the reply-to destination is an alias, service integration uses the alias bus and identifier, not the target bus and identifier. Service integration applications should not provide reply-to destinations that are foreign destinations or have names that include the @ character. Provided applications do not do this, processing is as follows:

  • The reply-to destination name (identifier) is stored in the ReplyToQ field and the reply-to destination bus name (that is, the local bus name) in the ReplyToQMgr field.

  • If the virtual queue manager name is different from the local bus name, the virtual queue manager name is stored in the ReplyToQMgr field instead of the local bus name.

If the real name of the reply-to destination does not comply with IBM MQ naming restrictions (including if the name includes the @ character), define an alias destination with a compliant name and the sending application must use the compliant (alias) name. In this case, define the alias destination in the local bus, not in the remote (indirectly-attached) bus.

MQRFH2 jms.Rto (JMSReplyTo)

If the message has a reply-to destination and the IBM MQ format message includes the MQRFH2 header, service integration constructs an IBM MQ URI to represent that reply-to destination, and stores the URI in the JMSReplyTo property in the IBM MQ message. If the reply-to destination is a queue, the URI includes the reply-to destination bus name (the local bus) or the virtual queue manager name (if that is different). If the message has a reverse-routing path, service integration includes that path in the URI in the ibmRoutingPath attribute.


Destination conversion when service integration converts a message from IBM MQ format

When service integration converts a message from IBM MQ format, it uses the following destination information from the IBM MQ format message:

MQXQH RemoteQName

MQXQH RemoteQMgrName

These fields are applicable only when service integration is receiving the message across an IBM MQ link, and only when the destination is a queue.

Service integration interprets the RemoteQName field as the destination identifier (always a queue) for the message, and the RemoteQMgrName field as the name of the destination bus for the message. If the RemoteQMgrName field contains the virtual queue manager name of the local bus, service integration interprets it as the name of the local bus. Service integration then uses the resulting bus and destination identifier combination (which can be an alias destination in the local bus) to deliver the message in the usual way. For the case where the destination bus is a foreign bus, this includes forwarding the message to that foreign bus.

MQRFH2 jms.Dst (JMSDestination)

If this field is available, service integration uses it to create the JMSDestination header field for the message. If the URI includes the ibmRoutingPath attribute, service integration uses that to create the forward-routing path for the message.

If this property is not available (for example, if the IBM MQ message has no MQRFH2 header), service integration can create a JMSDestination header field from the service integration destination where the message is delivered.

MQMD ReplyToQ

MQMD ReplyToQMgr

If these fields contain non-null values, service integration uses them to construct the first element of the reverse-routing path for the service integration message, as follows:

  • If ReplyToQMgr is the local bus name or virtual queue manager name, service integration sets the bus to the local bus and the destination name (identifier) to ReplyToQ.

  • If ReplyToQMgr is a foreign bus defined in the local bus, service integration sets the bus to ReplyToQMgr and the destination name (identifier) to ReplyToQ.

  • If ReplyToQMgr is not the local bus name, virtual queue manager name, or a foreign bus defined in the local bus, service integration sets the bus to the directly-attached IBM MQ bus and the destination name (identifier) to queue@queueManager where queue is ReplyToQ and queueManager is ReplyToQMgr.

MQRFH2 jms.Rto (JMSReplyTo)

If this field is available, service integration uses it with the MQMD ReplyToQ and ReplyToQMgr fields to construct the reverse-routing path and JMSReplyTo header field for the service integration message. It constructs the reverse-routing path from the first element (which it constructs from the MQMD ReplyToQ and ReplyToQMgr fields) and any remaining elements that it obtains from the ibmRoutingPath attribute (if there is one) of the JMSReplyTo URI in the IBM MQ message. It constructs the JMSReplyTo header field from the first element of the reverse-routing path together with the destination attributes of the JMSReplyTo URI in the IBM MQ message.