# Using Message Descriptors

A Message Descriptor is an attribute representing a property of the message, that is either being sent or received. For example, the Message Type of the message, the Message ID of the message, and the Priority of the message. For a detailed listing of all the message descriptors that are supported by the MQSeries control, see Table 10-1, "Elements of the MQMDHeaders XML document".

Using the MQSeries control, you can set Message Descriptors for each message while sending the message using the putMessage function. You can also get the message descriptors of the message that are retrieved from the queue. This facility is supported with the help of the MQMDHeaders document which is provided as an input to the putMessage and getMessage functions. The MQMDHeaders document is represented using an XMLBean, which conforms to the MQMDHeaders schema which is present in the MQSchemas.jar.

The following elements of the MQMDHeaders XML document can be set as part of the MQMD parameters:

Element Name | Description | Permissible Values | Relevance
--- | --- | --- | ---
MessageType | Message type of message | 8-Datagram 1-Request 2-Reply Other positive integers are also accepted, if they are within the Application or System defined ranges specified by MQSeries. | Put Request, Put Response, Get Response
MessageId | Message Id of message | Hexadecimal string | Put Request, Put Response, Get Request, Get Response
CorrelationId | Correlation Id of the message | Hexadecimal string | Put Request, Put Response, Get Request, Get Response
GroupMessage | This element is required while sending and receiving group messages. |  | Put Request, Put Response, Get Request, Get Response
GroupId | Group Id of the message | Hexadecimal string | Put Request, Put Response, Get Request, Get Response
Priority | Priority of the message | 0-9 | Put Request, Put Response, Get Response
Format | Format of the message | String values representing valid built-in MQSeries Formats or user-defined Formats. The string values are present in MQC.MQFMT_*. | Put Request, Put Response, Get Response
CharacterSet | Character Set of the message | Valid MQSeries Characterset | Put Request, Put Response, Get Response
Persistence | Persistence property of the message | 0-for a non-persistent message. 1-for persistent message | Put Request, Put Response, Get Response
Segmentation | Segmentation property of the message | 0-for segmentation not allowed. 1-for segmentation allowed. | Put Request
Expiry | Expiry of the message | Any positive integer or -1 (for unlimited expiry) | g Request, Put Response, Get Response
UserId | User Id of the message | Any string | Put Request, Put Response, Get Response
MessageSequenceNumber | Message Sequence Number of the message | Any positive integer other than 0 | Put Request, Put Response, Get Request, Get Response
GroupOptions | In the Put Request this element should be provided only if the message being Put is a group message. In the Get Response, this element appears only if the message retrieved is a group message. |  | Put Request, Get Response
IsLastMessage | Identifies the last message of a group message. this element accepts boolean values. | True or False | Put Request, Get Response
ReportOptions | Identifies the report options to be set while sending a message. |  | Put request
COA | Confirmation on Arrival. COA Report options COA-only the COA report without any data of the original message. COAWithData-the COA report with the first 100 bytes of the original message. COAWithFullData-the COA report with all the data of the original message | COA, COAWithData, COAWithFullData, None | Put Request
COD | Confirmation of Delivery COD Report options COD-only the COD report without any data of the original message. CODWithData-the COD report with the first 100 bytes of the original message. CODWithFullData-the COD report with all the data of the original message. | COD, CODWithData, CODWithFullData, None | Put request
Exception | Exception Report options Exception-only the Exception report without any data of the original message. ExceptionWithData-the Exception report with the first 100 bytes of the original message. ExceptionWithFullData-the Exception report with all the data of the original message. | Exception, ExceptionWithData, ExceptionWithFullData, None | Put request
Expiration | Expiration Report options Expiration-only the Expiration report without any data of the original message. ExpirationWithData-the Expiration report with the first 100 bytes of the original message. ExpirationWithFullData - The expiration report with all the data of the original message. | Expiration, ExpirationWithData, ExpirationWithFullData, None | Put request
Feedback | Feedback of the message | Positive integer value | Put Request, Put Response, Get Response
ReplyToQueueName | The queue to which the reports or the reply (only in the case of request message) should be sent. | String representing a valid queue name | Put Request, Put Response, Get Response
ReplyToQueueManager | The queue manager containing the reply to queue. | String representing a valid queue manager name | Put Request, Put Response, Get Response
WaitInterval | The interval to lapse (in milliseconds) before getting a message. | Any positive integer, or -1 for unlimited wait interval | Get request
ApplicationIdData |  | String value | Put request, Put response and Get response.
ApplicationOriginData |  | String value | Put request, Put response and Get response.
PutApplType | Put application type of the message | Positive integer value | Put request, Put response and Get response.
PutApplName | Put application name of the message | String value | Put request, Put response and Get response.
PutDateTime | Put date and time of the message | String value | Put response and Get response
AccountingToken | Accounting information for the message | Byte array | Put request, Put response and Get response.
Version | Version information of the message descriptor | 2 or 1 | Put request, Put response and Get response.
MessageConsumption | Message consumption option for the getMessage function. Browse-Retrieve the message from the queue (without deleting the message). Delete-Delete the message from the queue after retrieving it. | Browse, Delete | Get Request
MQGMO_CONVERT | Specify whether data conversion is required for the message during a Get operation. This element needs to be set to True for retrieving messages of the EBCDIC characterset. | True or False | Get request

Attribute Name | Under Element | Description | Values | Relevance
--- | --- | --- | --- | ---
waitForAllMsgs | GroupMessage | Used while retrieving group messages to specify that no message of the group should be retrieved until all the messages of the group are available in the queue. This attribute is normally specified only while retrieving the first message of the group. | True or False | Get request and Get response
logicalOrder | GroupMessage | Used while retrieving group messages to specify that the messages of the group should be retrieved in the order of their Message Sequence Number irrespective of the order in the queue. This option is specified while retrieving all the messages of the group. | True or False | Get request and Get response

### Schema of the MQMDHeaders Document

    <?xml version="1.0"?>
    <xs:schema targetNamespace="http://www.bea.com/wli/control/MQMDHeaders"
    xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://www.bea.com/wli/control/MQMDHeaders" elementFormDefault="qualified">
    <xs:element name="MQMDHeaders">
         <xs:complexType>
              <xs:sequence>
    <xs:element name="MessageType" type="xs:string" minOccurs="0"
    maxOccurs="1"/>
    <xs:element name="MessageId" type="xs:string" minOccurs="0" maxOccurs="1"/>
    <xs:element name="CorrelationId" type="xs:string" minOccurs="0" maxOccurs="1"/>
    <xs:element name="GroupMessage" minOccurs="0" maxOccurs="1"> <xs:complexType>
         <xs:sequence>
    <xs:element name="GroupId" type="xs:string" minOccurs="1" maxOccurs="1"/>
              </xs:sequence>
    <xs:attribute name="waitForAllMsgs" type="xs:boolean" use="optional"/>
    <xs:attribute name="logicalOrder" type="xs:boolean" use="optional"/>
         </xs:complexType>
              </xs:element>
    <xs:element name="Priority" type="xs:string" minOccurs="0" maxOccurs="1"/>
    <xs:element name="Format" type="xs:string" minOccurs="0" maxOccurs="1"/>
    <xs:element name="CharacterSet" type="xs:string" minOccurs="0"
    maxOccurs="1"/>
    <xs:element name="Persistence" type="xs:string" minOccurs="0" maxOccurs="1"/>
    <xs:element name="Segmentation" type="xs:string" minOccurs="0" maxOccurs="1"/>
    <xs:element name="Expiry" type="xs:string" minOccurs="0" maxOccurs="1"/>
    <xs:element name="UserId" type="xs:string" minOccurs="0" maxOccurs="1"/>
    <xs:element name="MessageSequenceNumber" type="xs:string" minOccurs="0"
    maxOccurs="1"/>
    <xs:element name="GroupOptions" minOccurs="0" maxOccurs="1">
         <xs:complexType>
              <xs:sequence>
                   <xs:element name="IsLastMessage" type="xs:boolean" minOccurs="1" maxOccurs="1"/>
              </xs:sequence>
         </xs:complexType>
    </xs:element>
    <xs:element name="ReportOptions" minOccurs="0" maxOccurs="1">
         <xs:complexType>
         <xs:sequence>
         <xs:element name="COA" type="xs:string" minOccurs="0" maxOccurs="1"/>
         <xs:element name="COD" type="xs:string" minOccurs="0" maxOccurs="1"/>
         <xs:element name="Exception" type="xs:string" minOccurs="0" maxOccurs="1"/>

         <xs:element name="Expiration" type="xs:string" minOccurs="0" maxOccurs="1"/>

         </xs:sequence>
         </xs:complexType>
         </xs:element>

    <xs:element name="Feedback" type="xs:int" minOccurs="0" maxOccurs="1"/> <xs:element name="ReplyToQueueName" type="xs:string" minOccurs="0" maxOccurs="1"/>
    <xs:element name="ReplyToQueueManager" type="xs:string" minOccurs="0" maxOccurs="1"/>
    <xs:element name="WaitInterval" type="xs:string" minOccurs="0" maxOccurs="1"/>
    <xs:element name="ApplicationIdData" type="xs:string" minOccurs="0" maxOccurs="1"/>
    <xs:element name="ApplicationOriginData" type="xs:string" minOccurs="0" maxOccurs="1"/>
    <xs:element name="PutApplType" type="xs:int" minOccurs="0" maxOccurs="1"/>
    <xs:element name="PutApplName" type="xs:string" minOccurs="0" maxOccurs="1"/>
    <xs:element name="PutDateTime" type="xs:string" minOccurs="0" maxOccurs="1"/>
    <xs:element name="AccountingToken" type="xs:base64Binary" minOccurs="0" maxOccurs="1"/>
    <xs:element name="Version" type="xs:string" minOccurs="0" maxOccurs="1"/>
    <xs:element name="MessageConsumption" type="xs:string" minOccurs="0" maxOccurs="1"/>
    <xs:element name="MQGMO_CONVERT" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
    </xs:sequence>
    </xs:complexType>
    </xs:element>
    </xs:schema>

### Sample of an MQMDHeaders Document

The following is a sample MQMDHeaders document that contains most of the message descriptors that you can set using MQSeries control:

    <?xml version="1.0"?>
    <even:MQMDHeaders xmlns:even="http://www.bea.com/wli/control/MQMDHeaders">
    <even:MessageType>8</even:MessageType>
    <even:MessageId>1111</even:MessageId> <even:CorrelationId>2222</even:CorrelationId>
    <even:GroupMessage>
         <even:GroupId>3333</even:GroupId>
    </even:GroupMessage>
    <even:Priority>9</even:Priority>
    <even:Format>MQSTR</even:Format> <even:CharacterSet>819</even:CharacterSet> <even:Persistence>1</even:Persistence> <even:Segmentation>1</even:Segmentation>
    <even:Expiry>5000</even:Expiry>
    <even:UserId>WebLogic</even:UserId> <even:MessageSequenceNumber>1</even:MessageSequenceNumber> <even:GroupOptions>
         <even:IsLastMessage>true</even:IsLastMessage>
    </even:GroupOptions>
    <even:ReportOptions>
         <even:COA>COAWithFullData</even:COA>
         <even:COD>CODWithFullData</even:COD>
         <even:Exception>ExceptionWithFullData</even:Exception>
         <even:Expiration>ExpirationWithFullData</even:Expiration> </even:ReportOptions>
    <even:Feedback>1</even:Feedback>
    <even:ReplyToQueueName>trial</even:ReplyToQueueName> <even:ReplyToQueueManager>QM_itpl_025051</even:ReplyToQueueManager> <even:ApplicationIdData>App_ID_025051</even:ApplicationIdData> <even:ApplicationOriginData>Windows_app_025051</even:ApplicationOriginData> <even:PutApplType>1</even:PutApplType> <even:PutApplName>MQSeriesClient</even:PutApplName> <even:Version>2</even:Version>
    </even:MQMDHeaders>

### Using XML Beans to Set the MQMDHeader Element Values

The MQSeries control MQMDHeaders document element values can be set and the return values can be retrieved, programmatically, by using XML beans. An example for setting the MQMDHeader element values prior to the putMessage function call is as follows:

    headers = com.bea.wli.control.mqmdHeaders.MQMDHeadersDocument.Factory.newInstance();com.bea.wli.control.mqmdHeaders.MQMDHeadersDocument.MQMDHeaders header = headers.addNewMQMDHeaders();
    header.setMessageType(MQC.MQMT_DATAGRAM);
    header.setPriority(8);
    header.setExpiry(5000);
    header.setPersistence(MQC.MQPER_PERSISTENT);
    header.getReportOptions().setCOA("COA"); header.setReplyToQueueName("ReportQueue"); header.setApplicationIdData("Testing"); header.setApplicationOriginData("AAAA");
    header.setPutApplName("Websphere MQ 2"); header.setPutApplType(MQC.MQAT_JAVA);