Composing Messages

You can create either a text message or a bytes message. A message, whether text or bytes, is composed of a header, properties, and a body. You can also create a message type which has no body.

Table 2–6 lists the functions you use to construct messages.

Table 2–6 Functions Used to Construct Messages

Function	Description
MQCreateMessage	Creates an MQ_MESSAGE type message.
MQCreateBytesMessage	Creates an MQ_BYTES_MESSAGE message.
MQCreateTextMessage	Creates an MQ_TEXT_MESSAGE message.
MQSetMessageHeaders	Sets message header properties. (Optional)
MQSetMessageProperties	Sets user-defined message properties.
MQSetStringProperty	Sets the body of an MQ_TEXT_MESSAGE message.
MQSetBytesMessageBytes	Sets the body of an MQ_BYTES_MESSAGE message.
MQSetMessageReplyTo	Specifies the destination where replies to this message should be sent.

Message Header

A header is required of every message. Header fields contain values used for routing and identifying messages.

Some header field values are set automatically by Message Queue during the process of producing and delivering a message, some depend on settings specified when message producers send a message, and others are set on a message-by-message basis by the client using the MQSetMessageHeader function. Table 2–7 lists the header fields defined (and required) by JMS and their corresponding names, as defined by the C-API.

Table 2–7 JMS-defined Message Header

JMS Message Header Field	C-API Message Header Property Name
JMSDestination	Defined implicitly when a producer sends a message to a destination, or when a consumer receives a message from a destination.
JMSDeliveryMode	MQ_PERSISTENT_HEADER_PROPERTY
JMSExpiration	MQ_EXPIRATION_HEADER_PROPERTY
JMSPriority	MQ_PRIORITY_HEADER_PROPERTY
JMSMessageID	MQ_MESSAGE_ID_HEADER_PROPERTY
JMSTimeStamp	MQ_TIMESTAMP_HEADER_PROPERTY
JMSRedelivered	MQ_REDELIVERED_HEADER_PROPERTY
JMSCorrelationID	MQ_CORRELATION_ID_HEADER_PROPERTY
JMSReplyTo	Set by the MQSetMessageReplyTo function, and obtained by the MQGetMessageReplyTo function.
JMSPriority	MQ_MESSAGE_TYPE_HEADER_PROPERTY

For additional information about each property type and who sets it, see MQSetMessageHeaders.

Message Body Types

JMS specifies six classes (or types) of messages. The C-API supports only three of these types, as described in Table 2–8. If a Message Queue C client expects to receive messages from a Message Queue Java client, it will be unable to process messages whose body types are other than those described in the table. It will also be unable to process messages that are compressed by the Message Queue Java client runtime.

Table 2–8 C-API Message Body Types

Type	Description
MQ_Text_Message	A message whose body contains an MQString string, for example an XML message.
MQ_Bytes_Message	A message whose body contains a stream of uninterpreted bytes.
MQ_Message	A message consisting of a header and (optional) properties, but no body.

Composing the Message

Create a message using either the MQCreateBytesMessage() function or the MQCreateTextMessage() function. Either of these functions returns a message handle that you can then pass to the functions you use to set the message body, header, and properties (listed in Composing Messages()). You can also use the MQCreateMessage() function to create a message that has a header and properties but no message body.

• Use the MQSetTextMessageText() function to define the body of a text message; use the MQSetBytesMessageBytes() function to define the body of a bytes message.

• Use the MQSetMessageHeaders() to set any message header properties.

  The message header can specify up to eight properties; most of these are set by the client runtime when sending the message or are set by the broker. The client can set MQ_CORRELATION_ID_HEADER_PROPERTY and MQ_MESSAGE_TYPE_HEADER_PROPERTY for sending a message.

• Use the MQSetMessageProperties() function to set any user-defined properties for this message.

When you set message header properties or when you set additional user-defined properties, you must pass a handle to a properties object that you have created using the MQCreateProperties() function. For more information, see Working With Properties.

You can use the MQSetMessageReplyTo() function to associate a message with a destination that recipients can use for replies. To do this, you must first create a destination that will serve as your reply-to destination. Then, pass a handle to that destination when you call the MQSetMessageReplyTo() function. The receiver of a message can use the MQGetMessageReplyTo() function to determine whether a sender has set up a destination where replies are to be sent.