WebSphere WebSphere Business Integration Message Service Clients for C/C++ Version 1.2.7 and .NET Version 1.2.6 Operating Systems: AIX, Linux, Solaris, Windows

Message

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.

Related reference
XMS messages

Functions

Summary of functions:
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.

xmsMsgAcknowledge – Acknowledge

Interface:
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 Message acknowledgement.

Parameters:
message (input)
The handle for the message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_ILLEGAL_STATE_EXCEPTION

xmsMsgClearBody – Clear Body

Interface:
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.

Parameters:
message (input)
The handle for the message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgClearProperties – Clear Properties

Interface:
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.

Parameters:
message (input)
The handle for the message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgDispose – Delete Message

Interface:
xmsRC xmsMsgDispose(xmsHMsg *message,
                    xmsHErrorBlock errorBlock);

Delete the message.

If an application tries to delete a message that is already deleted, the call is ignored.

Parameters:
message (input)
On input, the handle for the message. On output, the function returns a null handle.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgGetJMSCorrelationID – Get JMSCorrelationID

Interface:
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.

Parameters:
message (input)
The handle for the message.
correlID (output)
The buffer to contain the correlation identifier.
length (input)
The length of the buffer in bytes. If you specify a length of 0, the correlation identifier is not returned, but its length is returned in the actualLength parameter.
actualLength (output)
The length of the correlation identifier in bytes. If you specify a null pointer on input, the length is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgGetJMSDeliveryMode – Get JMSDeliveryMode

Interface:
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.

Parameters:
message (input)
The handle for the message.
deliveryMode (output)
The delivery mode of the message, which is one of the following values:
  • XMSC_DELIVERY_PERSISTENT
  • XMSC_DELIVERY_NOT_PERSISTENT

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_NOT_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().

errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgGetJMSDestination – Get JMSDestination

Interface:
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.

Parameters:
message (input)
The handle for the message.
destination (output)
The handle for the destination of the message.

For a newly created message that has not been sent, the function returns a null handle and an error 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().

errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgGetJMSExpiration – Get JMSExpiration

Interface:
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.

Parameters:
message (input)
The handle for the message.
expiration (output)
The expiration time of the message.

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().

errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgGetJMSMessageID – Get JMSMessageID

Interface:
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.

Parameters:
message (input)
The handle for the message.
msgID (output)
The buffer to contain the message identifier.

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().

length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE instead, the message identifier is not returned, but its length is returned in the actualLength parameter.
actualLength (output)
The length of the message identifier in bytes. If you specify a null pointer on input, the length is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
XMS_X_GENERAL_EXCEPTION
Notes:
  1. If a message has no message identifier, the function leaves the contents of the buffer unchanged, sets the actualLength parameter to 0, and returns an error.

xmsMsgGetJMSPriority – Get JMSPriority

Interface:
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.

Parameters:
message (input)
The handle for the message.
priority (output)
The priority of the message. The value is an integer in the range 0, the lowest priority, to 9, the highest priority.

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().

errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgGetJMSRedelivered – Get JMSRedelivered

Interface:
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.

Parameters:
message (input)
The handle for the message.
redelivered (output)
The value is xmsTRUE if the message is being re-delivered. The value is xmsFALSE if the message is not being re-delivered.

For a real-time connection to a broker, the value is always xmsFALSE.

errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgGetJMSReplyTo – Get JMSReplyTo

Interface:
xmsRC xmsMsgGetJMSReplyTo(xmsHMsg message,
                          xmsHDest *destination,
                          xmsHErrorBlock errorBlock);

Get the destination where a reply to the message is to be sent.

Parameters:
message (input)
The handle for the message.
destination (output)
The handle for the destination where a reply to the message is to be sent. A null handle means that no reply is expected.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgGetJMSTimestamp – Get JMSTimestamp

Interface:
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.

Parameters:
message (input)
The handle for the message.
timeStamp (output)
The time when the message was sent.

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().

errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
Note:
  1. If the time stamp is undefined, the function sets the timeStamp parameter to 0 but returns no error.

xmsMsgGetJMSType – Get JMSType

Interface:
xmsRC xmsMsgGetJMSType(xmsHMsg message,
                       xmsCHAR *type,
                       xmsINT length,
                       xmsINT *actualLength,
                       xmsHErrorBlock errorBlock);

Get the type of the message.

For more information about how to use this function, see C functions that return a string by value.

Parameters:
message (input)
The handle for the message.
type (output)
The buffer to contain the type of the message. If data conversion is required, this is the type after conversion.
length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE instead, the type of the message is not returned, but its length is returned in the actualLength parameter.
actualLength (output)
The length of the type of the message in bytes. If data conversion is required, this is the length after conversion. If you specify a null pointer on input, the length is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgGetProperties – Get Properties

Interface:
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.

Note: The equivalent JMS method performs a slightly different function. The JMS method returns an enumeration of only the names of the properties of the message, not their values.
Parameters:
message (input)
The handle for the message.
iterator (output)
The handle for the iterator.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgGetTypeId – Get Type

Interface:
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.

Parameters:
message (input)
The handle for the message.
type (output)
The body type of the message, which is one of the following values:
  • XMS_MESSAGE_TYPE_BASE (the message has no body)
  • XMS_MESSAGE_TYPE_BYTES
  • XMS_MESSAGE_TYPE_MAP
  • XMS_MESSAGE_TYPE_OBJECT
  • XMS_MESSAGE_TYPE_STREAM
  • XMS_MESSAGE_TYPE_TEXT
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgPropertyExists – Check Property Exists

Interface:
xmsRC xmsMsgPropertyExists(xmsHMsg message,
                           xmsCHAR *propertyName,
                           xmsBOOL *propertyExists,
                           xmsHErrorBlock errorBlock);

Check whether the message has a property with the specified name.

Parameters:
message (input)
The handle for the message.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyExists (output)
The value is xmsTRUE if the message has a property with the specified name. The value is xmsFALSE if the message does not have a property with the specified name.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgSetJMSCorrelationID – Set JMSCorrelationID

Interface:
xmsRC xmsMsgSetJMSCorrelationID(xmsHMsg message,
                                xmsCHAR *correlID,
                                xmsINT length,
                                xmsHErrorBlock errorBlock);

Set the correlation identifier of the message.

Parameters:
message (input)
The handle for the message.
correlID (input)
The correlation identifier as a character array.
length (input)
The length of the correlation identifier in bytes. If the correlation identifier is null terminated with no embedded null characters, you can specify XMSC_CALCULATE_STRING_SIZE instead and allow XMS to calculate its length.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgSetJMSDeliveryMode – Set JMSDeliveryMode

Interface:
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.

Parameters:
message (input)
The handle for the message.
deliveryMode (input)
The delivery mode of the message, which must be one of the following values:
  • XMSC_DELIVERY_PERSISTENT
  • XMSC_DELIVERY_NOT_PERSISTENT
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgSetJMSDestination – Set JMSDestination

Interface:
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.

Parameters:
message (input)
The handle for the message.
destination (input)
The handle for the destination of the message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgSetJMSExpiration – Set JMSExpiration

Interface:
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.

Parameters:
message (input)
The handle for the message.
expiration (input)
The expiration time of the message expressed in milliseconds since 00:00:00 GMT on the 1 January 1970.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgSetJMSMessageID – Set JMSMessageID

Interface:
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.

Parameters:
message (input)
The handle for the message.
msgID (input)
The message identifier as a character array.
length (input)
The length of the message identifier in bytes. If the message identifier is null terminated with no embedded null characters, you can specify XMSC_CALCULATE_STRING_SIZE instead and allow XMS to calculate its length.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgSetJMSPriority – Set JMSPriority

Interface:
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.

Parameters:
message (input)
The handle for the message.
priority (input)
The priority of the message. The value can be an integer in the range 0, the lowest priority, to 9, the highest priority.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgSetJMSRedelivered – Set JMSRedelivered

Interface:
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.

Parameters:
message (input)
The handle for the message.
redelivered (input)
The value xmsTRUE means that the message is being re-delivered. The value xmsFALSE means that the message is not being re-delivered.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgSetJMSReplyTo – Set JMSReplyTo

Interface:
xmsRC xmsMsgSetJMSReplyTo(xmsHMsg message,
                          xmsHDest destination,
                          xmsHErrorBlock errorBlock);

Set the destination where a reply to the message is to be sent.

Parameters:
message (input)
The handle for the message.
destination (input)
The handle for the destination where a reply to the message is to be sent. A null handle means that no reply is expected.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgSetJMSTimestamp – Set JMSTimestamp

Interface:
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.

Parameters:
message (input)
The handle for the message.
timeStamp (input)
The time when the message is sent expressed in milliseconds since 00:00:00 GMT on the 1 January 1970.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMsgSetJMSType – Set JMSType

Interface:
xmsRC xmsMsgSetJMSType(xmsHMsg message,
                       xmsCHAR *type,
                       xmsINT length,
                       xmsHErrorBlock errorBlock);

Set the type of the message.

Parameters:
message (input)
The handle for the message.
type (input)
The type of the message as a character array.
length (input)
The length of the type of the message in bytes. If the type of the message is null terminated with no embedded null characters, you can specify XMSC_CALCULATE_STRING_SIZE instead and allow XMS to calculate its length.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

Reference topic

Terms of Use | Rate this page

Last updated: 18 Jun 2008

© Copyright IBM Corporation 2005, 2008. All Rights Reserved.