# Sending and Receiving Messages

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

### Sending Messages

To send a message, select a putMessage function based on the data type of the message that you want to send:

- 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 is sent. If a value is not provided at 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. If the MQMDHeadersDocument parameter is not provided, or if the parameter is null, the message is put into the queue with the default values for the message descriptors.

The return value of the function is the MQMDHeadersDocument representing the MQMD attributes of the message sent to the queue.

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

The following 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, enter a name for the new method.
3. Click Add, then select MQMDHeadersDocument from the XML Types list. Enter 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, then select String from the Java datatype list. Enter 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, then select String from the Java datatype list. Enter 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 must provide variable names for all 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 in which to store the output of the putMessageAsString function, the MQMDHeaders document, which represents the attributes of the message that was sent.

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

### Sending Messages To a Remote Queue Manager

Using the MQSeries control you can add messages to a remote queue managed by a remote queue manager. To do this, you must configure a transmission queue in the queue manager to which the MQSeries control is connected. For more information on how to configure a transmission queue, see the MQSeries documentation on http://www.IBM.com.

To add a message to a remote queue (managed by a remote queue manager) you must drag and drop the following function, before the putMessage call in the workflow:

void setRemoteQueueManager(java.lang.String remoteQueueManager);

The parameter to this function is the name of the remote queue manager. To set the value for this parameter, in the Design View, open the remoteQueueManager node. In the Send Data tab, select or create a string variable, then enter the name of your remote queue manager as the default value.

Once you've configured the remote queue manager, the putMessage functions following the setRemoteQueueManager function add messages to the remote queue manager.

To revert to the default (local) queue manager to which your control is connected, in the Design View you must drag and drop the setRemoteQueueManager again in your workflow. On doing this, a default value, null, is passed as the parameter to this function. This null value or empty string reverts control back to the default queue manager. messages are now automatically added to the local queue.

### Receiving Messages

To receive a message, select a get Message function based on the data type of the message that you want to receive:

- 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, java.lang.String queue, is the name of the queue from which the message is to be received. If a value is not provided at runtime (the value is null) the default queue name mentioned in the control property is used.

The second parameter of the function, MQMDHeadersDocument, is an XML bean. This represents the MQMDHeadersDocument provided as an XML document at runtime, which conforms to the MQMDHeaders schema. The values provided in this document are used to retrieve the message corresponding to the MQMD attributes specified in the document. If the MQMDHeadersDocument parameter is not provided, or if the parameter is null, the first message present in the queue is retrieved. If the MQMDHeadersDocument parameter is not null, the MQMD attributes of the message obtained from the queue are updated in this XML bean object itself.

Note: If the MQMDHeadersDocument parameter to the getMessage function is null, you must use the getMQMDHeaders function after the getMessage function in the workflow, to get the MQMD attributes of the message retrieved from the queue. Also, if the MQMDHeadersDocument parameter to the getMessage function is null, Delete is used as the default MessageConsumption option.

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 procedure describes how to add a MQSeries control getMessage function to a business process.

1. Open the Client Request node.
2. In the General Settings tab, enter a name for the new method.
3. Click Add, then select MQMDHeadersDocument from the XML Types list. Enter 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, then select String from the Java datatype list. Enter 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 must enter variable names for the two variables. The variable type is pre-defined based on the parameters to which they are assigned.
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 in which to store the output of the getMessageAsString function. The output is a string representing the message that was retrieved from the queue.

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

You can use a similar procedure to retrieve messages using the getMessageAsBytes or the getMessageAsXml functions.

### Sending Group messages

You can send group messages using the MQSeries control putMessage function within a loop. The loop can be created using one of the following process nodes: While Do, Do while, and For Each.

Provide the GroupOptions element in the MQMDHeadersDocument. You only provide this element in the input MQMDHeaders XML document 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 the last message, the IsLastMessage element must be set to True.

If you specify a GroupID for the first message, then 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 using the MQSeries control getMessage function within a loop. The loop can be created using one of the following process nodes: While Do, Do while, and For Each.

#### Setting the logicalorder Attribute

You can retrieve group messages using the MQSeries control in a logical order. To configure the 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 when you use explicit transaction mode. The following figure depicts a sample workflow for retrieving group messages in logical order:

The loop executes 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 does 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 retrieve the messages of the group in their logical order (by message sequence number, beginning at one for the first message).

Changing the logicalOrder attribute from True to False while getting group messages, when its value was True in the previous Get service call, changes the logical ordering.

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

The following is an example of a Get Request MQMDHeaders document for retrieving group messages in logical order, and also waits for all messages in the group:

    <?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 the 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 the 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 means 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

GroupId is an optional element within the GroupMessage element. Its value may not be provided if the hexadecimal group ID of the group message is not known. When there are multiple group messages present in the queue, the first group message 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.

#### Setting the MessageSequenceNumber Element

Group Messages can also be retrieved by specifying the MessageSequenceNumber element and the GroupId. Messages can be retrieved in this way 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. The group messages can still be retrieved in a loop by providing the GroupId and incrementing the MessageSequenceNumber by one in each Get function call in the loop, the MessageSequenceNumber of the first message being one.