A Message object represents a message that an application sends or receives.
For a list of the JMS message header fields in a Message object, see Header fields in an XMS message. For a list of the JMS defined properties of a Message object, see JMS defined properties of a message. For a list of the IBM defined properties of a Message object, see IBM defined properties of a message.
Function | Description |
---|---|
xmsMsgAcknowledge | Acknowledge this message and all previously unacknowledged messages received by the session. |
xmsMsgClearBody | Clear the body of the message. |
xmsMsgClearProperties | Clear the properties of the message. |
xmsMsgDispose | Delete the message. |
xmsMsgGetJMSCorrelationID | Get the correlation identifier of the message. |
xmsMsgGetJMSDeliveryMode | Get the delivery mode of the message. |
xmsMsgGetJMSDestination | Get the destination of the message. |
xmsMsgGetJMSExpiration | Get the expiration time of the message. |
xmsMsgGetJMSMessageID | Get the message identifier of the message. |
xmsMsgGetJMSPriority | Get the priority of the message. |
xmsMsgGetJMSRedelivered | Get an indication of whether the message is being re-delivered. |
xmsMsgGetJMSReplyTo | Get the destination where a reply to the message is to be sent. |
xmsMsgGetJMSTimestamp | Get the time when the message was sent. |
xmsMsgGetJMSType | Get the type of the message. |
xmsMsgGetProperties | Get a list of the properties of the message. |
xmsMsgGetTypeId | Get the body type of the message. |
xmsMsgPropertyExists | Check whether the message has a property with the specified name. |
xmsMsgSetJMSCorrelationID | Set the correlation identifier of the message. |
xmsMsgSetJMSDeliveryMode | Set the delivery mode of the message. |
xmsMsgSetJMSDestination | Set the destination of the message. |
xmsMsgSetJMSExpiration | Set the expiration time of the message. |
xmsMsgSetJMSMessageID | Set the message identifier of the message. |
xmsMsgSetJMSPriority | Set the priority of the message. |
xmsMsgSetJMSRedelivered | Indicate whether the message is being re-delivered. |
xmsMsgSetJMSReplyTo | Set the destination where a reply to the message is to be sent. |
xmsMsgSetJMSTimestamp | Set the time when the message is sent. |
xmsMsgSetJMSType | Set the type of the message. |
xmsRC xmsMsgAcknowledge(xmsHMsg message, xmsHErrorBlock errorBlock);
Acknowledge this message and all previously unacknowledged messages received by the session.
An application can call this function if the acknowledgement mode of the session is XMSC_CLIENT_ACKNOWLEDGE. Calls to the function are ignored if the session has any other acknowledgement mode or is transacted.
Messages that have been received but not acknowledged might be re-delivered.
For more information about acknowledging messages, see Acknowledging the receipt of messages in a session.
xmsRC xmsMsgClearBody(xmsHMsg message, xmsHErrorBlock errorBlock);
Clear the body of the message. The header fields and message properties are not cleared.
If an application clears a message body, the body is left in the same state as an empty body in a newly created message. The state of an empty body in a newly created message depends on the type of message body. For more information, see The body of an XMS message.
An application can clear a message body at any time, no matter what state the body is in. If a message body is read-only, the only way that an application can write to the body is for the application to clear the body first.
xmsRC xmsMsgClearProperties(xmsHMsg message, xmsHErrorBlock errorBlock);
Clear the properties of the message. The header fields and the message body are not cleared.
If an application clears the properties of a message, the properties become readable and writable.
An application can clear the properties of a message at any time, no matter what state the properties are in. If the properties of a message are read-only, the only way that the properties can become writable is for the application to clear the properties first.
xmsRC xmsMsgDispose(xmsHMsg *message, xmsHErrorBlock errorBlock);
If an application tries to delete a message that is already deleted, the call is ignored.
xmsRC xmsMsgGetJMSCorrelationID(xmsHMsg message, xmsCHAR *correlID, xmsINT length, xmsINT *actualLength, xmsHErrorBlock errorBlock);
Get the correlation identifier of the message.
For more information about how to use this function, see C functions that return a string by value.
xmsRC xmsMsgGetJMSDeliveryMode(xmsHMsg message, xmsINT *deliveryMode, xmsHErrorBlock errorBlock);
Get the delivery mode of the message. The delivery mode is set by the xmsMsgProducerSend() call when the message is sent.
For a newly created message that has not been sent, the delivery mode is XMSC_DELIVERY_PERSISTENT, except for a real-time connection to a broker for which the delivery mode is XMSC_DELIVERY_NON_PERSISTENT. For a message that has been received, the function returns the delivery mode that was set by the xmsMsgProducerSend() call when the message was sent unless the receiving application changes the delivery mode by calling xmsMsgSetJMSDeliveryMode().
xmsRC xmsMsgGetJMSDestination(xmsHMsg message, xmsHDest *destination, xmsHErrorBlock errorBlock);
Get the destination of the message. The destination is set by the xmsMsgProducerSend() call when the message is sent.
For a newly created message that has not been sent, the function returns a null handle and error code XMS_E_NOT_SET unless the sending application sets a destination by calling xmsMsgSetJMSDestination(). For a message that has been received, the function returns a handle for the destination that was set by the xmsMsgProducerSend() call when the message was sent unless the receiving application changes the destination by calling xmsMsgSetJMSDestination().
xmsRC xmsMsgGetJMSExpiration(xmsHMsg message, xmsLONG *expiration, xmsHErrorBlock errorBlock);
Get the expiration time of the message.
The expiration time is set by the xmsMsgProducerSend() call when the message is sent. Its value is calculated by adding the time to live, as specified by the sending application, to the time when the message is sent. The expiration time is expressed in milliseconds since 00:00:00 GMT on the 1 January 1970.
If the time to live is 0, the xmsMsgProducerSend() call sets the expiration time to 0 to indicate that the message does not expire.
XMS discards expired messages and does not deliver them to applications.
For a newly created message that has not been sent, the expiration time is 0 unless the sending application sets a different expiration time by calling xmsMsgSetJMSExpiration(). For a message that has been received, the function returns the expiration time that was set by the xmsMsgProducerSend() call when the message was sent unless the receiving application changes the expiration time by calling xmsMsgSetJMSExpiration().
xmsRC xmsMsgGetJMSMessageID(xmsHMsg message, xmsCHAR *msgID, xmsINT length, xmsINT *actualLength, xmsHErrorBlock errorBlock);
Get the message identifier of the message. The message identifier is set by the xmsMsgProducerSend() call when the message is sent.
For more information about how to use this function, see C functions that return a string by value.
For a message that has been received, the function returns the message identifier that was set by the xmsMsgProducerSend() call when the message was sent unless the receiving application changes the message identifier by calling xmsMsgSetJMSMessageID().
xmsRC xmsMsgGetJMSPriority(xmsHMsg message, xmsINT *priority, xmsHErrorBlock errorBlock);
Get the priority of the message. The priority is set by the xmsMsgProducerSend() call when the message is sent.
For a newly created message that has not been sent, the priority is 4 unless the sending application sets a different priority by calling xmsMsgSetJMSPriority(). For a message that has been received, the function returns the priority that was set by the xmsMsgProducerSend() call when the message was sent unless the receiving application changes the priority by calling xmsMsgSetJMSPriority().
xmsRC xmsMsgGetJMSRedelivered(xmsHMsg message, xmsBOOL *redelivered, xmsHErrorBlock errorBlock);
Get an indication of whether the message is being re-delivered. The indication is set by the xmsMsgConsumerReceive() call when the message is received.
For a real-time connection to a broker, the value is always xmsFALSE.
xmsRC xmsMsgGetJMSReplyTo(xmsHMsg message, xmsHDest *destination, xmsHErrorBlock errorBlock);
Get the destination where a reply to the message is to be sent.
xmsRC xmsMsgGetJMSTimestamp(xmsHMsg message, xmsLONG *timeStamp, xmsHErrorBlock errorBlock);
Get the time when the message was sent. The time stamp is set by the xmsMsgProducerSend() call when the message is sent and is expressed in milliseconds since 00:00:00 GMT on the 1 January 1970.
For a newly created message that has not been sent, the time stamp is 0 unless the sending application sets a different time stamp by calling xmsMsgSetJMSTimestamp(). For a message that has been received, the function returns the time stamp that was set by the xmsMsgProducerSend() call when the message was sent unless the receiving application changes the time stamp by calling xmsMsgSetJMSTimestamp().
xmsRC xmsMsgGetJMSType(xmsHMsg message, xmsCHAR *type, xmsINT length, xmsINT *actualLength, xmsHErrorBlock errorBlock);
For more information about how to use this function, see C functions that return a string by value.
xmsRC xmsMsgGetProperties(xmsHMsg message, xmsHIterator *iterator, xmsHErrorBlock errorBlock);
Get a list of the properties of the message.
The function returns an iterator that encapsulates a list of Property objects. The application can then use the iterator to access each property in turn.
xmsRC xmsMsgGetTypeId(xmsHMsg message, xmsMESSAGE_TYPE *type, xmsHErrorBlock errorBlock);
Get the body type of the message.
For information about message body types, see The body of an XMS message.
xmsRC xmsMsgPropertyExists(xmsHMsg message, xmsCHAR *propertyName, xmsBOOL *propertyExists, xmsHErrorBlock errorBlock);
Check whether the message has a property with the specified name.
xmsRC xmsMsgSetJMSCorrelationID(xmsHMsg message, xmsCHAR *correlID, xmsINT length, xmsHErrorBlock errorBlock);
Set the correlation identifier of the message.
xmsRC xmsMsgSetJMSDeliveryMode(xmsHMsg message, xmsINT deliveryMode, xmsHErrorBlock errorBlock);
Set the delivery mode of the message.
A delivery mode set by this function before the message is sent is ignored and replaced by the xmsMsgProducerSend() call when the message is sent. However, you can use this function to change the delivery mode of a message that has been received.
xmsRC xmsMsgSetJMSDestination(xmsHMsg message, xmsHDest destination, xmsHErrorBlock errorBlock);
Set the destination of the message.
A destination set by this function before the message is sent is ignored and replaced by the xmsMsgProducerSend() call when the message is sent. However, you can use this function to change the destination of a message that has been received.
xmsRC xmsMsgSetJMSExpiration(xmsHMsg message, xmsLONG expiration, xmsHErrorBlock errorBlock);
Set the expiration time of the message.
An expiration time set by this function before the message is sent is ignored and replaced by the xmsMsgProducerSend() call when the message is sent. However, you can use this function to change the expiration time of a message that has been received.
xmsRC xmsMsgSetJMSMessageID(xmsHMsg message, xmsCHAR *msgID, xmsINT length, xmsHErrorBlock errorBlock);
Set the message identifier of the message.
A message identifier set by this function before the message is sent is ignored and replaced by the xmsMsgProducerSend() call when the message is sent. However, you can use this function to change the message identifier of a message that has been received.
xmsRC xmsMsgSetJMSPriority(xmsHMsg message, xmsINT priority, xmsHErrorBlock errorBlock);
Set the priority of the message.
A priority set by this function before the message is sent is ignored and replaced by the xmsMsgProducerSend() call when the message is sent. However, you can use this function to change the priority of a message that has been received.
xmsRC xmsMsgSetJMSRedelivered(xmsHMsg message, xmsBOOL redelivered, xmsHErrorBlock errorBlock);
Indicate whether the message is being re-delivered.
An indication of re-delivery set by this function before the message is sent is ignored by the xmsMsgProducerSend() call when the message is sent, and is ignored and replaced by the xmsMsgConsumerReceive() call when the message is received. However, you can use this function to change the indication for a message that has been received.
xmsRC xmsMsgSetJMSReplyTo(xmsHMsg message, xmsHDest destination, xmsHErrorBlock errorBlock);
Set the destination where a reply to the message is to be sent.
xmsRC xmsMsgSetJMSTimestamp(xmsHMsg message, xmsLONG timeStamp, xmsHErrorBlock errorBlock);
Set the time when the message is sent.
A time stamp set by this function before the message is sent is ignored and replaced by the xmsMsgProducerSend() call when the message is sent. However, you can use this function to change the time stamp of a message that has been received.
xmsRC xmsMsgSetJMSType(xmsHMsg message, xmsCHAR *type, xmsINT length, xmsHErrorBlock errorBlock);