Programming Considerations Using MSMQ-MQSeries Bridge Extensions

The limitations of specific API functions result from the fact that MSMQ-MQSeries Bridge transmits messages, not API calls, between queuing systems. The MSMQ-MQSeries Bridge transmits messages across the MSMQ-MQSeries interface. The MSMQ-MQSeries Bridge does not transmit API calls across the interface. Thus, Microsoft® Message Queuing (also known as MSMQ) API calls operate only within the Message Queuing environment, and MQSeries API calls operate only within the MQSeries environment. This principle limits the ways in which you can create and access queues.

All Message Queuing API functions operate only within the Message Queuing environment, up to and including foreign computers and queues. For example, you can use the following functions:

MQLocateBegin, MQLocateNext, and MQLocateEnd to search for foreign queues
MQGetMachineProperties, MQGetPrivateComputerInformation, MQGetQueueProperties, and MQGetQueueSecurity functions to retrieve the properties of foreign queues
MQOpenQueue to open a foreign queue
MQSetQueueProperties and MQSetQueueSecurity to set the properties of foreign queues
MQCloseQueue to close a foreign queue

When creating a queue, you can call the Message Queuing function MQCreateQueue to create a foreign queue representing an MQSeries queue, but you cannot create the actual MQSeries queue itself. Similarly, you cannot create a Message Queuing queue by calling the MQSeries function MQOPEN.

To communicate across the MSMQ-MQSeries interface, your Message Queuing and MQSeries applications should each create their own queues. Alternatively, you can use administration tools such as the Message Queuing Manager or the MQSeries command interface to create the queues.

For proper message delivery, you must ensure that the destination queue for each message actually exists.

You can use the Message Queuing MQPathNameToFormatName function to determine a Message Queuing format name for an MQSeries queue. The format name actually refers to the Message Queuing foreign queue. The MSMQ-MQSeries Bridge processes the format name that it finds in a message and directs the message to the MQSeries queue.

When opening a queue, a call to the Message Queuing function MQOpenQueue opens the foreign queue, not the MQSeries queue itself. The MSMQ-MQSeries Bridge opens the MQSeries queue as necessary when it transmits a message. If you are sending messages to more that one MQSeries queue, you must open each one separately using its own Message Queuing format name.

In the opposite direction, the MQSeries function MQOPEN opens the transmission queue for the Message Queuing computer. The MSMQ-MQSeries Bridge opens the Message Queuing queue when it transmits a message.

When sending a Message Queuing message to a foreign queue with MQSendMessage, Message Queuing delivers the message to the connector queue in the MSMQ-MQSeries Bridge computer. The MSMQ-MQSeries Bridge converts and transmits the message to MQSeries queue. MQSeries delivers a message sent by MQPUT to a transmission queue. The MSMQ-MQSeries Bridge reads the message from the MQSeries transmission queue. After converting the message from MQSeries to Message Queuing message properties, MSMQ-MQSeries Bridge transmits the message to the destination Message Queuing queue.

When receiving a message, the MSMQ-MQSeries Bridge does not transmit receive requests across the MSMQ-MQSeries interface. A Message Queuing application can receive a message only from a native Message Queuing queue (the MQReceiveMessage function). An MQSeries application can receive only from a native MQSeries queue (the MQGET function).

When sending a message from MQSeries to Message Queuing, if you want the MQSeries message to have a value for MQMD.ApplIdentityData, you need the set both of the following:

Set the Open option with MQOO_SET_IDENTITY_CONTEXT
Set the Put option with MQPMO_SET_IDENTITY_CONTEXT

When a message is retrieved from Message Queuing, the MSMQ-MQSeries Bridge will have converted the Message Queuing PROPID_M_LABEL and PROPID_M_LABEL_LEN properties from the MQSeries MQMD.ApplIdentityData field value.

The MQMDE extension has the following GUID for MQMD version 2.

static const GUID sg_MSMQExtMQMDE = 
{ 0x18ae68f5, 0x989b, 0x11d3, 
    { 0x8d, 0xf9, 0x0, 0x0, 0xf8, 0x1a,  0xea, 0x1f }
};

This section contains:

To download updated Host Integration Server 2004 Help from www.microsoft.com, go to http://go.microsoft.com/fwlink/?linkid=29507.