Network Deployment (Distributed operating systems), v8.0 > Reference > Developer best practices


Map destinations to and from WebSphere MQ queues, topics, and destinations

Service integration messages and WebSphere 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 WebSphere 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 WebSphere MQ format.


Destinations and destination properties in the WebSphere MQ format message

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

MQXQH RemoteQName

MQXQH RemoteQMgrName

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

The RemoteQName field contains the name of the send-to queue ( WebSphere MQ) or send-to destination (service integration). The RemoteQMgrName field identifies the queue manager or queue-sharing group ( WebSphere 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 a WebSphere 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 WebSphere MQ naming restrictions.

MQRFH2 jms.Dst (JMSDestination)

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

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

When service integration sends a message that has a forward-routing path to WebSphere MQ, it adds an ibmRoutingPath attribute to this URI. The ibmRoutingPath value identifies the forward routing path from the service integration message. WebSphere 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 WebSphere MQ format messages.

If the sending application specifies a reply-to queue, the ReplyToQ field contains the name of the reply-to queue ( WebSphere MQ) or reply-to destination (service integration), and the ReplyToQMgr field identifies the queue manager or queue-sharing group ( WebSphere 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 a WebSphere 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 WebSphere MQ naming restrictions.

MQRFH2 jms.Rto (JMSReplyTo)

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

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

When service integration sends a message that has a reverse-routing path to WebSphere 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, WebSphere 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 WebSphere MQ format

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

MQXQH RemoteQName

MQXQH RemoteQMgrName

These fields apply only when service integration is sending the message across a WebSphere 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 WebSphere MQ naming restrictions, define an alias destination with a compliant name; the sending application must use the compliant (alias) name. In this case, 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 WebSphere 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 WebSphere MQ naming restrictions, see How to address bus destinations and WebSphere MQ queues.

MQRFH2 jms.Dst (JMSDestination)

If the WebSphere MQ format message includes the MQRFH2 header, service integration serializes the JMSDestination header field into a WebSphere MQ URI and stores it in the JMSDestination field in the WebSphere 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 by 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 WebSphere 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 WebSphere MQ format message includes the MQRFH2 header, service integration constructs a WebSphere MQ URI to represent that reply-to destination, and stores the URI in the JMSReplyTo property in the WebSphere 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 WebSphere MQ format

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

MQXQH RemoteQName

MQXQH RemoteQMgrName

These fields are applicable only when service integration is receiving the message across a WebSphere 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 to create the forward-routing path for the message.

If this property is not available (for example, if the WebSphere 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 WebSphere 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 WebSphere 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 WebSphere MQ message.


Foreign destinations and alias destinations
Configurations that include WebSphere MQ
How to address bus destinations and WebSphere MQ queues
Create an alias destination on a bus
Configure alias destination properties


Related


WebSphere MQ naming restrictions
http://www.ibm.com/software/integration/wmq/library

+

Search Tips   |   Advanced Search