# Sending and Receiving Messages

You can send and receive messages using the MQSeries control, by using the Put and Get functions. You can send and receive messages in the form of Bytes, String or XML data.

### Sending Messages

Depending on the data type of the message that you want to send, you can use any of the following putMessage functions:

- MQMDHeadersDocument putMessageAsBytes (byte[] message, java.lang.String queue, MQMDHeadersDocument mqmd) throws ResourceException;
- MQMDHeadersDocument putMessageAsString (String message, java.lang.String queue, MQMDHeadersDocument mqmd) throws ResourceException;
- MQMDHeadersDocument putMessageAsXml (XmlObject message, java.lang.String queue, MQMDHeadersDocument mqmd) throws ResourceException;

The first parameter that is passed to the function is the message to be put into the queue. The possible types for this parameter are byte[], XmlObject and String for sending Binary, XML and plain text messages respectively.

The second parameter that is passed to the function is the queue to which the message needs to be Put. If no value is provided during runtime, that is, if the value is null, the default queue name mentioned in the control property is used.

The third parameter that is passed to the function is the XML bean representing the MQMDHeadersDocument provided as an XML document during runtime, which conforms to the MQMDHeaders schema. The values provided in this document are used for setting the MQMD attributes of the message being sent.

The return value of the function is the MQMDHeadersDocument representing the MQMD attributes of the message Put into the queue.

#### Using the putMessage Function In a Business Process

The following sample procedure describes how to add any MQSeries control putMessage function to a business process.

1. Open the Client Request node.
2. In the General Settings tab, provide a name for the new method.
3. Click Add, and select MQMDHeadersDocument from the XML Types list. Provide a name for the variable in the Name field. Click OK to add your selection to the Client Request node. This represents the input MQMDHeaders document for the putMessage function.
4. Click Add again, and select String from the Java datatype list. Provide a name for the variable in the Name field. Click OK to add your selection to the Client Request node. This represents the queue name for the putMessage function.
5. Click Add again, and select String from the Java datatype list. Provide a name for the variable in the Name field. Click OK to add your selection to the Client Request node. This represents the message for the putMessage function.
6. In the Receive Data tab, create a new variable for each of the three parameters that you created in the General Settings tab of the Client Request node. You need to provide variable names for all the three variables. The variable type is pre-defined, based on the parameters to which you are assigning the variable.
7. Close the Client Request node.
8. Drag and drop the putMessageAsString function from the Controls tab in the Data Palette into your business process, just below the Client Request node.
9. Open the Send Data tab of the putMessageAsString function node. From the Select variables to assign drop-down list, assign the variables that you created in the Receive Data tab of the Client Request node, to the corresponding parameter of the putMessageAsString function listed in the Control Expects column.
10. Open the Receive Data tab of the putMessageAsString function node. From the Select variables to assign drop-down list, create a new variable to store the output of the putMessageAsString function which is the MQMDHeaders document, which represents the attributes of the message that was sent.

You can use similar steps to send messages using putMessageAsBytes or putMessageAsXml functions.

### Receiving Messages

Depending on the data type of the message that you want to receive, you can use any of the following getMessage functions:

- byte[] getMessageAsBytes(java.lang.String queue, MQMDHeadersDocument mqmd) throws ResourceException;
- String getMessageAsString(java.lang.String queue, MQMDHeadersDocument mqmd) throws ResourceException;
- XmlObject getMessageAsXml(java.lang.String queue, MQMDHeadersDocument mqmd) throws ResourceException;

The first parameter of the function is the queue from which the message is to be received. If no value is provided during runtime, that is, if the value is null, the default queue name mentioned in the control property is used.

The second parameter to this function is the XML bean representing the MQMDHeadersDocument provided as an XML document during runtime, which conforms to the MQMDHeaders schema. The values provided in this document are used for retrieving the message corresponding to the MQMD attributes specified in the document. The MQMD attributes of the message obtained from the queue are updated in this XML bean object itself.

The return value of the function is the message obtained from the queue. The data type of the message depends on the getMessage function added. The values may be byte[], XmlObject or String depending on whether the message obtained is to be processed as a Binary, XML or plain text message.

#### Using the getMessage Function In a Business Process

The following sample procedure describes how to add any MQSeries control getMessage function to a business process.

1. Open the Client Request node.
2. In the General Settings tab, provide a name for the new method.
3. Click Add, and select MQMDHeadersDocument from the XML Types list. Provide a name for the variable in the Name field. Click OK to add your selection to the Client Request node. This represents the input MQMDHeaders document for the getMessage function.
4. Click Add again, and select String from the Java datatype list. Provide a name for the variable in the Name field. Click OK to add your selection to the Client Request node. This represents the queue name for the getMessage function.
5. In the Receive Data tab, create a new variable for each of the two parameters that you created in the General Settings tab of the Client Request node. You need to provide variable names for the two variables. The variable type is pre-defined, based on the parameters to which you are assigning the variable.
6. Close the Client Request node.
7. Drag and drop the getMessageAsString function from the Controls tab in the Data Palette into your business process, just below the Client Request node.
8. Open the Send Data tab of the getMessageAsString function node. From the Select variables to assign drop-down list, assign the variables that you created in the Receive Data tab of the Client Request node, to the corresponding parameter of the getMessageAsString function listed in the Control Expects column.
9. Open the Receive Data tab of the getMessageAsString function node. From the Select variables to assign drop-down list, create a new variable to store the output of the getMessageAsString function which is a String that represents the message that was retrieved from the queue.

The Message Descriptor attributes of the message that was retrieved from the queue are updated in the MQMDHeaders document that was provided as input to the getMessageAsString function.

You can use similar steps to retrieve messages using getMessageAsBytes or getMessageAsXml functions.

### Sending Group messages

You can send Group Messages by configuring your business process containing the putMessage function of the MQSeries control, within a loop configured using one of the While do, Do While, and For Each process nodes.

To send group messages, provide the GroupOptions element in the MQMDHeadersDocument. You need to provide this element in the input MQMDHeaders XML document only if a group message is to be sent.

In the MQMDHeaders document, set the IsLastMessage element within GroupOptions to False, for all messages except the last message, for which the IsLastMessage element has to be set to True.

If you specify a GroupId for the first message, the MQSeries control assigns this Id to the group message. If you do not specify a GroupId for the first message, the MQSeries queue manager assigns a group Id to the first message. This Id is returned in the output MQMDHeaders document of the putMessage function.

The Group Id assigned to the first message must be used for all the subsequent messages of the group. The MessageSequenceNumber of the first message of the group should be 1; the MessageSequenceNumber of the second message should be 2, and so on.

### Retrieving Group Messages

You can retrieve group Messages by configuring your business process containing the getMessage function of the MQSeries control, within a loop configured using one of the While do, Do While, and For Each process nodes.

#### Setting the logicalorder Attribute

The MQSeries control supports retrieving group messages in a logical order. To configure MQSeries control to retrieve group messages in a logical order, set the logicalOrder attribute of the GroupMessage element to True.

You can retrieve messages in a logical order only if you are using the explicit transaction mode. The following figure depicts a sample workflow for retrieving group messages in logical order:

The loop can be continued until the IsLastMessage element within the GroupOptions element is set to True in the response MQMDHeaders document of the getMessage function.

Note: The GroupOptions element will not appear in the Get Response MQMDHeaders document if the retrieved message is not a part of a group.

The logicalOrder attribute must be set to True in each call of the Get service to get all the messages of the group in their logical order (in the order of their message sequence number starting from 1 for the first message).

Setting the logicalOrder to False in the midst of getting group messages, when its value was True in the previous Get service call would disturb the logical ordering.

Setting the logicalOrder attribute to False or not providing this attribute in the Get request document would mean that the control would get the first message of the group as it appears on the queue irrespective of its message sequence number.

The Get Request MQMDHeaders document for retrieving group messages in logical order and also wait for all messages of the group, looks as follows:

    <?xml version="1.0"?>
    <even:MQMDHeaders xmlns:even="http://www.bea.com/wli/control/MQMDHeaders"> <even:GroupMessage waitForAllMsgs="true" logicalOrder="true"> 	<even:GroupId></even:GroupId>
    </even:GroupMessage>
    <even:MessageConsumption>Delete</even:MessageConsumption>
    </even:MQMDHeaders>

#### Setting the waitForAllMsgs Attribute

You can configure MQSeries control to wait for all messages of the group to be present in the queue before retrieving any message within the group. To configure MQSeries control to wait for all messages, set the waitForAllMsgs attribute of the GroupMessage element to True.

Note: The waitForAllMsgs and the logicalOrder attribute are optional and can be set to either True or False.

You can set the waitForAllMsgs to True while retrieving the first message of the group. After you retrieve the first message in the group, you can set this attribute to True again, for retrieving the other messages of the group, provided that you have also set the logicalOrder attribute to True.

Setting the waitForAllMsgs attribute to False or not providing this attribute in the Get request document would mean that the control can still get group messages from the queue even when not all of the messages of the group are present in the queue.

#### Setting the GroupId element

The GroupId is an optional element that you can set under the GroupMessage element and its value may not be provided if the hexadecimal group id of the group message is not known. In case there are multiple group messages in the queue, the first group message appearing in the queue is retrieved. The GroupId value may be specified, if known. If specified, and there are multiple group messages in the queue, the group message matching the group id is retrieved.

#### Retrieving Group Messages Using MessageSequenceNumber Element

Group Messages can also be retrieved by specifying the MessageSequenceNumber element and the GroupId. But this can be used only if the logicalOrder attribute value is False or is not provided. When the MessageSequenceNumber and the GroupId are provided, the message of the group matching the MessageSequenceNumber is retrieved. So the group messages can still be retrieved in a loop by providing the GroupId and incrementing the MessageSequenceNumber by 1 in each Get function call in the loop, the MessageSequenceNumber of the first message being 1.