How the MQGet node implements IBM MQ MQGet API calls

Review how the MQGet node processes the input messages to construct the output messages, based on both the content of the local environment tree and the input parameters that you set.

You can include an MQGet node anywhere in a message flow, including a flow that implements a request-response scenario. The MQGet node receives an input message on its input terminal from the preceding node in the message flow, issues an MQGET call to retrieve a message from the IBM® MQ queue that you have configured in its properties, and builds a result message tree. Finally, it uses the input tree and the result tree to create 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 MQGET operation.

How the MQGet node handles the local environment

The MQGet node examines the local environment tree that is propagated from the preceding node, uses the content that is related to the MQGMO (MQ Get Message Options) and the MQMD (MQ Message Descriptor header), and updates the local environment:

  • The node reads the MQGMO structure from ${inputMQParmsLocation}.MQGMO.*.
  • The node copies the IBM MQ completion and reason codes to ${outputMQParmsLocation}.CC and ${outputMQParmsLocation}.RC.
  • The node writes the complete MQGMO that is used for the MQGET call into ${outputMQParmsLocation}.MQGMO if ${inputMQParmsLocation}.MQGMO exists in the input tree.
  • The node writes the MQMD that is passed to the MQGET call (that contains the values that are specified in the input message or are generated by the node) into ${inputMQParmsLocation}.MQMD, deleting any existing content.

Set the value to ${inputMQParmsLocation} in the MQGet node property Input MQ Parameters Location on the Request Properties tab.

Set the value to ${outputMQParmsLocation} in the MQGet node property Output MQ Parameters Location on the Result Properties tab.

For more information about these properties, see MQGet node.

In summary:
${inputMQParmsLocation}
  • QueueName: Optional override for MQGet node Queue Name property
  • InitialBufferSize: Optional override for MQGet node Initial Buffer Size property
  • MQGMO.*: Optional MQGET message options that are used by the MQGet node
${outputMQParmsLocation}
  • CC: MQGET call completion code
  • RC: MQGET call result code
  • MQGMO.*: MQGET message options that are used if present in ${inputMQParmsLocation}
  • MQMD: unparsed MQ Message Descriptor for received messages1
  • Browsed: Set to true if the message is browsed. Not present if the message is removed from the queue
You can parse the MQMD (for example, by using ESQL), where ${outputMQParmsLocation} is LocalEnvironment.MQ.GET:
DECLARE ptr REFERENCE TO OutputLocalEnvironment.MyMQParms;
CREATE FIRSTCHILD OF ptr DOMAIN('MQMD') PARSE(InputLocalEnvironment.MQ.GET.MQMD)

How the MQMD for the MQGET call is constructed

  • A default MQMD is prepared. For further information about the MQMD, see the Application Programming Reference section of the IBM MQ Version 7.5 product documentation online.
  • If you do not supply an input MQMD, the default MQMD is used.
  • If you do supply an input MQMD, the default MQMD is used after the following modifications:
    • If the property Use all input MQMD fields is set, all MQMD fields supplied are copied into the default MQMD from the input MQMD.
    • If the property Use all input MQMD fields is not set and the properties Get by Message ID or Get by Correlation ID are selected, the respective IDs are copied into the default MQMD from the input MQMD.

The following diagram shows how the MQGet node constructs the MQMD that is used on the call to IBM MQ:

The diagram is described in the text above.

How the output message tree is constructed

The following diagram outlines how the MQGet node constructs the output message tree, combining the input tree from the previous node with the result tree from the MQGET call:

The diagram is described in the text above.

In this example, the MQGet node properties are configured as shown in the following table.
Property Action
Copy Message Copy Entire Message
Generate Mode Message
Output Data Location OutputRoot.XMLNS.A
Result Data Location ResultRoot.XMLNS.C
The MQGet node constructs the output tree 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.XMLNS.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 retains the name A.

The following diagram shows this behavior:

The diagram is described in the text above.

For some examples of message trees that are constructed by the MQGet node according to the rules described above, see MQGet node message tree examples.