Sending a Message

Messages are sent by a message producer within the context of a connection and a session. Once you have obtained a connection, created a session, and composed your message, you can use the functions listed in Table 2–9to create a message producer and to send the message.

Which function you choose to send a message depends on the following factors:

• Whether you want the send function to override certain message header properties

  Send functions whose names end in Ext allow you to override default values for priority, time-to-live, and delivery mode header properties.

• Whether you want to send the message to the destination associated with the message producer

  If you created a message producer with no specified destination, you must used one of the ...ToDestination send functions. If you created a message producer with a specified destination, you must use one of the other send functions.

If you send a message using one of the functions that does not allow you to override header properties, the following message header fields are set to default values by the send function.

• MQ_PERSISTENT_HEADER_PROPERTY will be set to MQ_PERSISTENT_DELIVERY.

• MQ_PRIORITY_HEADER_PROPERTY will be set to 4.

• MQ_EXPIRATION_HEADER_PROPERTY will be set to 0, which means that the message will never expire.

To override these values, use one of the extended send functions. For a complete list of message header properties, see MQGetMessageHeaders .

Message headers also contain fields that can be set by the sending client; in addition, you can set user-defined message properties as well. For more information, see Composing Messages.

You can set the connection property MQ_ACK_ON_PRODUCE_PROPERTY when you create the connection to make sure that the message has reached its destination on the broker:

• By default, the broker acknowledges receiving persistent messages only.

• If you set the property to MQ_TRUE, the broker acknowledges receipt of all messages (persistent and non-persistent) from the producing client.

• If you set the property to MQ_FALSE, the broker does not acknowledge receipt of any message (persistent or non-persistent) from the producing client.

Note that “acknowledgement” in this case is not programmatic but internally implemented. That is, the client thread is blocked and does not return until the broker acknowledges messages it receives.

An administrator can set a broker limit, REJECT_NEWEST, which allows the broker to avert memory problems by rejecting the newest incoming message. If the incoming message is persistent, then an error is returned which the sending client should handle, perhaps by retrying the send a bit later. If the incoming message is not persistent, the client has no way of knowing that the broker rejected it. The broker might also reject a message if it exceeds a specified limit.