Using an MQGet node in a request-response flow

For details of the processing done within the MQGet node to achieve the above, see MQGet node message processing. For details on constructing this type of flow, see the sample Coordinated Request Reply sample

Introduction

This page is an introduction to the use of an MQGet node in a request-response flow, and describes how the node processes the input messages (according to the LocalEnvironment and input parameters you set) to construct the output messages.

A request-response flow between two applications allows one of the applications to request messages from the other. This type of flow is illustrated in the following diagram:

The image is described in the text below.

In the diagram, the Requesting Application places a message into the "Request" input queue of the Replying Application. The Replying Application then processes the message and sends a reply to the "Reply" queue specified in the original message from the Requesting Application.

If one of these applications is to be replaced or enhanced without making changes to the other, then messages will need to be transformed between the two applications. To achieve this, the Broker can be inserted between them, as shown in the following diagram:

The image is described in the text below.

Now a queue alias, or a similar device, is configured so that the Requesting Application places its request message into the input queue of the "Coordinated Request Reply" Broker message flow. In the previous example this message was placed directly into the input queue of the Replying Application. The "Coordinated Request Reply" flow transforms the message to a format suitable for the Replying Application, and passes it on to its input queue. It also saves the original Requesting Application's reply-to queue details, and restores these to the reply message it receives from the Replying Application so it can be posted back correctly to the Requesting Application.

An MQGet node can be placed anywhere in a flow and receives on its input terminal an input tree propagated from the preceding node. It then uses the message retrieved from the configured WebSphere MQ queue to build a result tree. Finally, it uses the input tree and the result tree to build an output tree that is then propagated to its output, warning or failure terminal depending on the configuration of the node and the result of the Get operation.

For more details on constructing a flow, see the sample: Coordinated Request Reply sample.

How the LocalEnvironment is used

The LocalEnvironment propagated from the preceding node is read and updated by the MQGet node.

  • The MQGMO structure will be read from ${inputMQParmsLocation}.MQGMO.*
  • MQ completion and reason codes will be placed in ${outputMQParmsLocation}.CC and .RC
  • If an MQGMO tree exists in the local environment, it will be updated with the values used by the node and propagated downstream
  • If ${inputMQParmsLocation}.MQMD exists, then the MQMD passed to the MQGET call itself (containing the values specified in the input message or generated by the node) will be placed in that location, deleting anything already in that location.

${inputMQParmsLocation} is the value set in the MQGet Node Property Input MQ Parameters Location on the Request Properties tab.

${outputMQParmsLocation} is the value set in the MQGet Node Property Output MQ Parameters Location on the Result Properties tab.

For details of these properties, see MQGet node.

In summary:
${inputMQParmsLocation}
  • QueueName: Optional override for MQGet Node Property Queue Name.
  • InitialBufferSize: Optional override for MQGet Node Property Initial Buffer Size.
  • MQGMO.*: Optional MQ Get message options the MQGet Node will use.
${outputMQParmsLocation}
  • CC: MQ Get call completion code.
  • RC: MQ Get call result code.
  • MQGMO.*: MQ Get message options use if present in ${inputMQParmsLocation}.
  • MQMD: MQ Message Descriptor for received messages.

How the MQMD for the MQGet call is constructed

  • If you do not supply an input MQMD then a default MQMD, as described in the WebSphere MQ Application Programming Reference, is used.
  • If you do supply an input MQMD, then it is used in one of the two following ways:
    • If the attribute Use complete input MQMD is set, the input MQMD is used in its entirety.
    • If the attribute Use complete input MQMD is not set, a default MQMD is prepared, then from the input MQMD, if the check boxes messageID or correlID are set, then the respective IDs are copied into it.

The following diagram shows in a little more detail how the MQGet node constructs the MQMD to be used on the call to WebSphere MQ:

The diagram is described in the text above.

How the output message tree is constructed

The following diagram outlines how the output message tree is constructed by combining the input tree from the previous node with the result tree from the MQGet call:

The diagram is described in the text above.

Here is an example, where the MQGet Node properties are configured as listed:
copyMessage
copyEntireMessage
generateMode
message
outputDataLocation
OutputRoot.XML.A
resultDataLocation
ResultRoot.XML.C
In this example the Output tree is constructed according to the following sequence:
  1. The whole of the Input tree is copied to the Output tree, including the XML branch with child A and A's child B.
  2. From the Result tree, the XML branch's child C and C's child D are put into the Output tree at position OutputRoot.XML.A. Any previous content of A (values and children) is lost, and replaced with C's content, including all values and children it has, in this case child D.
  3. The position in the Output tree remains named A.
The following diagram illustrates this visually:

The diagram is described in the text above.

Message tree examples

Here are some examples of how message trees are constructed according to the rules outlined above.

Table 1. An example Input, LocalEnvironment and MQGet
With a message assembly like this: The message that MQGet returns is:
InputRoot
MQMD
{input message mqmd}
MQRFH2
{input message mqrfh2}
XMLNS
{input message body}
InputLocalEnvironment
MQ
GET
MQGMO
MatchOptions = MQMO_MATCH_CORREL_ID
MQMD (with no children)
MyData
MQMD
{input mqmd} (with CorrelID = {correct Correlation ID as binary})
Start of change
ResultRoot
MQMD
{result message mqmd}
MQRFH2
{result message mqrfh2}
XML
{result message body}
End of change
Table 2. Example resulting output message trees, according to the MQGet Node properties settings detailed.
With the following settings: The resulting output message assembly is:
inputMQMDLocation
InputLocalEnvironment.MyData.MQMD
copyMessage
copyEntireMessage
copyLocalEnv
copyEntireLocalEnvironment
generateMode
messageAndLocalEnvironment
outputDataLocation
InputLocalEnvironment.MyData.ReturnedMessage
OutputRoot
MQMD
{input message mqmd}
MQRFH2
{input message mqrfh2}
XMLNS
{input message body}
OutputLocalEnvironment
MQ
GET
MQGMO
{mqgmo used for get}
MQMD
{mqmd used for get}
CC = 0
RC = 0
MyData
MQMD
{input mqmd} (with CorrelID = {correct Correlation ID as binary})
ReturnedMessage
MQMD
{result message mqmd}
MQRFH2
{result message mqrfh2}
XML
{result message body}
resultDataLocation
ResultRoot.XML
OutputRoot
MQMD
{input message mqmd}
MQRFH2
{input message mqrfh2}
XMLNS
{input message body}
OutputLocalEnvironment
MQ
GET
MQGMO
{mqgmo used for get}
MQMD
{mqmd used for get}
CC = 0
RC = 0
MyData
MQMD
{input mqmd} (with CorrelID = {correct Correlation ID as binary})
ReturnedMessage (with any attributes and value from ResultRoot.XML)
{result message body}

This tree is effectively the result of doing an assignment from ${resultDataLocation} to ${outputDataLocation}. The value of the source element is copied, as are all children including attributes.

copyLocalEnv
none
OutputRoot
MQMD
{input message mqmd}
MQRFH2
{input message mqrfh2}
XMLNS
{input message body}
OutputLocalEnvironment
MQ
GET
MQGMO
{mqgmo used for get}
MQMD
{mqmd used for get}
CC = 0
RC = 0
MyData
ReturnedMessage (with any attributes and value from ResultRoot.XML)
{result message body}

This tree has the MQMD used for the get in the OutputLocalEnvironment because the input MQ parameters location had an MQMD element under it. Even though the input tree is not copied, the presence of the MQMD element causes the MQMD used for the get to be placed in the output tree.

outputDataLocation
<blank>
copyLocalEnv
copyEntireLocalEnvironment
OutputRoot
MQMD
{result message mqmd}
MQRFH2
{result message mqrfh2}
XMLNS
{result message body}
OutputLocalEnvironment
MQ
GET
MQGMO
{mqgmo used for get}
MQMD
{mqmd used for get}
CC = 0
RC = 0
MyData
MQMD
{input mqmd} (with CorrelID = {correct Correlation ID as binary})

The setting of copyMessage in this case makes no difference to the eventual output tree.

Related concepts
Message flows overview