> tibemsMsg
> Type
> Purpose
> Messages carry information among EMS client programs.
> Related Types
> tibemsBytesMsg, tibemsMapMsg, tibemsObjectMsg, tibemsStreamMsg, tibemsTextMsg

> Function | Description | Page
> Receipt
> tibemsMsg_Acknowledge | Acknowledge messages. | 24
> Body
> tibemsMsg_GetBodyType | Get the body type of a message. | 35
> Message Life Cycle
> tibemsMsg_ClearBody | Clear the body of a message. | 26
> tibemsMsg_ClearProperties | Clear the properties of a message. | 27
> tibemsMsg_Create | Create a message object. | 28
> tibemsMsg_CreateCopy | Create a copy of the message object. | 29
> tibemsMsg_CreateFromBytes | Create a message object from data in a byte sequence. | 30
> tibemsMsg_Destroy | Destroy a message. | 31
> tibemsMsg_MakeWriteable | Make a message writeable. | 53
> Output
> tibemsMsg_GetAsBytes | Get a byte sequence representation of the message object. | 32
> tibemsMsg_GetAsBytesCopy | Copies a byte sequence representation of the message object into storage supplied by the program. | 33
> tibemsMsg_GetByteSize | Computes the size of the byte sequence representation of the message. | 36
> tibemsMsg_Print | Print a message. | 54
> tibemsMsg_PrintToBuffer | Prints a message into a buffer. | 55
> Headers and Properties For details, see Headers.
> tibemsMsg_ClearProperties | Clear the properties of a message. | 27
> tibemsMsg_GetCorrelationID | Get the correlation ID header of a message. | 37
> tibemsMsg_GetDeliveryMode | Get the delivery mode header from a message. | 39
> tibemsMsg_GetDestination | Get the destination header from a message. | 40
> tibemsMsg_GetEncoding | Get the character encoding header from a message. | 41
> tibemsMsg_GetExpiration | Get the expiration header from a message. | 42
> tibemsMsg_GetMessageID | Get the message ID header from a message. | 43
> tibemsMsg_GetPriority | Get the priority header from a message. | 44
> tibemsMsg_Get Property | Get the value of a message property. | 45
> tibemsMsg_GetPropertyNames | Get a list of property names from a message. | 48
> tibemsMsg_GetRedelivered | Get the redelivered header from a message. | 49
> tibemsMsg_GetReplyTo | Get the reply-to header from a message. | 50
> tibemsMsg_GetTimestamp | Get the timestamp header from a message. | 51
> tibemsMsg_GetType | Get the type header of a message. | 52
> tibemsMsg_PropertyExists | Test whether a named property has been set on a message. | 56
> tibemsMsg_SetCorrelationID | Set the correlation ID header of a message. | 57
> tibemsMsg_SetDeliveryMode | Set the delivery mode header of a message. | 59
> tibemsMsg_SetDestination | Set the destination header of a message. | 60
> tibemsMsg_SetEncoding | Set the character encoding header of a message. | 61
> tibemsMsg_SetExpiration | Set the expiration header of a message. | 62
> tibemsMsg_SetMessageID | Set the message ID header of a message. | 63
> tibemsMsg_SetPriority | Set the priority header of a message. | 64
> tibemsMsg_SetRedelivered | Set the redelivered header of a message. | 68
> tibemsMsg_SetReplyTo | Set the reply-to header of a message. | 69
> tibemsMsg_SetTimestamp | Set the timestamp header of a message. | 70
> tibemsMsg_SetType | Set the type header of a message. | 71
> tibemsMsg_Set Property | Set the value of a message property. | 65

> Table 7 Message Constants
> Constant | Description
> TIBEMS_DEFAULT_DELIVERY_MODE | TIBEMS_PERSISTENT When neither the sending call nor the producer supplies a delivery mode, this default applies.
> TIBEMS_DEFAULT_PRIORITY | 4 When neither the sending call nor the producer supplies a priority, this default applies. See also, Priority.
> TIBEMS_DEFAULT_TIME_TO_LIVE | 0 When neither the sending call nor the producer supplies a priority, this default applies. The default value, zero, indicates that messages do not expire. See also Expiration.

> tibemsMsg_Acknowledge
> Function
> Purpose
> Acknowledge messages.
> C Declaration
> tibems_status tibemsMsg_Acknowledge(
> tibemsMsg message );
> COBOL Call
> CALL "tibemsMsg_Acknowledge"
> USING BY VALUE message,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Acknowledge this message (but for the actual behavior of this call, see the Remarks below).

> Remarks
> The behavior of this call depends on the acknowledgement mode of the tibemsSession.

> ● | In TIBEMS_CLIENT_ACKNOWLEDGE mode, this call acknowledges all messages that the program has consumed within the session. (This behavior complies with the JMS specification.)

> ● | In TIBEMS_EXPLICIT_CLIENT_ACKNOWLEDGE mode, this call acknowledges only the individual message. (This mode and behavior are proprietary extensions, specific to TIBCO EMS.)

> ● | In TIBEMS_EXPLICIT_CLIENT_DUPS_OK_ACKNOWLEDGE mode, this call lazily acknowledges only the individual message. Lazy means that the provider client library can delay transferring the acknowledgement to the server until a convenient time; meanwhile the server might redeliver the message. (This mode and behavior are proprietary extensions, specific to TIBCO EMS.)

> ● | In all other modes, this call has no effect. In particular, modes that specify transactions or implicit acknowledgement do not require the consuming program to call this function. However, calling it does not produce an exception. (This behavior complies with the JMS specification.)

> Consumed
> Two events mark a message as consumed—that is, eligible for acknowledgment using this function:

> ● | Just before the provider calls an tibemsMsgCallback function, it marks the message argument as consumed.

> ● | Just before a receive call returns a message, it marks that message as consumed.

> Redelivery
> The server might redeliver unacknowledged messages.
> Restriction
> It is illegal to call this function after closing the session, the connection or the consumer through which the message arrived.
> See Also
> tibemsMsgConsumer_Receive on page 168
> tibemsSession on page 286
> tibemsAcknowledgeMode on page 313
> tibemsMsg_ClearBody
> Function
> Purpose
> Clear the body of a message.
> C Declaration
> tibems_status tibemsMsg_ClearBody(
> tibemsMsg message );
> COBOL Call
> CALL "tibemsMsg_ClearBody"
> USING BY VALUE message,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Message to be cleared.

> Remarks
> Clearing the body of a message leaves its header and property values unchanged.
> If the message body was read-only, this function makes it writeable. The message body appears and behaves identically to an empty body in a newly created message.
> tibemsMsg_ClearProperties
> Function
> Purpose
> Clear the properties of a message.
> C Declaration
> tibems_status tibemsMsg_ClearProperties(
> tibemsMsg message );
> COBOL Call
> CALL "tibemsMsg_ClearProperties"
> USING BY VALUE message,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Message to be cleared.

> Remarks
> Clearing the property values of a message leaves its header values and body unchanged.
> tibemsMsg_Create
> Function
> Purpose
> Create a message object.
> C Declaration
> tibems_status tibemsMsg_Create(
> tibemsMsg* message );
> COBOL Call
> CALL "tibemsMsg_Create"
> USING BY REFERENCE message,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | The function stores a pointer to the new message in this location.

> Remarks
> This call creates a new message.
> When your application creates a message, it also allocates storage for that message. This storage must subsequently be freed by a call to tibemsMsg_Destroy.
> See Also
> tibemsMsg_Destroy on page 31
> tibemsMsg_CreateCopy
> Function
> Purpose
> Create a copy of the message object.
> C Declaration
> tibems_status tibemsMsg_CreateCopy(
> const tibemsMsg message,
> tibemsMsg* copy );
> COBOL Call
> CALL "tibemsMsg_CreateCopy"
> USING BY VALUE message,
> BY REFERENCE copy,
> RETURNING tibems-status
> END-CALL.

> | message and copy have usage pointer.

> Parameters

> Parameter | Description
> message | Copy this message.
> copy | The function stores a pointer to the new copy in this location.

> Remarks
> This call creates a new message by copying an existing message.
> The copy is completely independent of the original message. Pointer data in fields are independent copies of the original values.
> This function copies the entire message, including headers, properties, and body data.
> This function allocates the storage for the copy. The duration of the copy is independent of the original message. Your program owns the messages that it creates, and must destroy those messages to reclaim the storage. That is, each call to this function must be paired with a call to tibemsMsg_Destroy.
> See Also
> tibemsMsg_Destroy on page 31
> tibemsMsg_CreateFromBytes
> Function
> Purpose
> Create a message object from data in a byte sequence.
> C Declaration
> tibems_status tibemsMsg_CreateFromBytes(
> tibemsMsg* message,
> const void* bytes );
> COBOL Call
> CALL "tibemsMsg_CreateFromBytes"
> USING BY REFERENCE message,
> BY REFERENCE bytes,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | The function stores a pointer to the new message in this location.
> bytes | Create a message from the data in this byte sequence. This data buffer represents the message in EMS wire format. To produce this type of buffer, use either tibemsMsg_GetAsBytes or tibemsMsg_GetAsBytesCopy.

> Remarks
> This call creates a new message from a byte sequence and populates the message with data.
> This function allocates the storage for the new message. Your program owns the messages that it creates, and must destroy those messages to reclaim the storage. That is, each call to this function must be paired with a call to tibemsMsg_Destroy.
> The new message is independent of the original byte sequence. They do not share any storage.
> The newly created message is read-only; to enable modification without erasing the content, call tibemsMsg_MakeWriteable.
> See Also
> tibemsMsg_Destroy on page 31
> tibemsMsg_GetAsBytes on page 32
> tibemsMsg_GetAsBytesCopy on page 33
> tibemsMsg_MakeWriteable on page 53
> tibemsMsg_Destroy
> Function
> Purpose
> Destroy a message.
> C Declaration
> tibems_status tibemsMsg_Destroy(
> tibemsMsg message );
> COBOL Call
> CALL "tibemsMsg_Destroy"
> USING BY VALUE message,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Destroy this message.

> tibemsMsg_GetAsBytes
> Function
> Purpose
> Get a byte sequence representation of the message object.
> C Declaration
> tibems_status tibemsMsg_GetAsBytes(
> const tibemsMsg message,
> const void** bytes,
> tibems_int* actual_size );
> COBOL Call
> CALL "tibemsMsg_GetAsBytes"
> USING BY VALUE message,
> BY REFERENCE bytes,
> BY REFERENCE actual-size,
> RETURNING tibems-status
> END-CALL.

> | message and bytes have usage pointer.

> Parameters

> Parameter | Description
> message | Fill the byte array with the content of this message.
> bytes | The function allocates a byte sequence, and stores a pointer to it in this location.
> actual_size | The function stores the length of the byte sequence in this location.

> Remarks
> This call formats the data of the message as a byte sequence in EMS wire format, which is suitable for archiving in a file.
> The function allocates storage for the byte sequence, and associates it with the message; the byte sequence storage persists until your program destroys the message object.
> Your program must not modify the byte sequence. To make a modifiable byte sequence, use tibemsMsg_GetAsBytesCopy instead.
> The byte sequence includes data from the message header, message properties, and all message fields.
> The byte sequence might contain interior null bytes.
> See Also
> tibemsMsg_CreateFromBytes on page 30
> tibemsMsg_GetAsBytesCopy on page 33
> tibemsMsg_GetByteSize on page 36
> tibemsMsg_GetAsBytesCopy
> Function
> Purpose
> Copies a byte sequence representation of the message object into storage supplied by the program.
> C Declaration
> tibems_status tibemsMsg_GetAsBytesCopy(
> const tibemsMsg message,
> const void* bytes,
> tibems_int avail_size,
> tibems_int* actual_size );
> COBOL Call
> CALL "tibemsMsg_GetAsBytesCopy"
> USING BY VALUE message,
> BY REFERENCE bytes,
> BY VALUE avail-size,
> BY REFERENCE actual-size,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Fill the byte array with the content of this message.
> bytes | Your program must supply storage suitable for a byte sequence. The function stores the byte sequence in this location.
> avail_size | The length of the storage available for the byte sequence.
> actual_size | The function stores the length of the byte sequence in this location.

> Remarks
> This call formats the data of the message as a byte sequence in EMS wire format, which is suitable for archiving in a file.
> Your program must allocate storage for the byte sequence, and supply a pointer to it as an argument.
> The byte sequence includes data from the message header, message properties, and all message fields.
> The byte sequence might contain interior null bytes.

> Status Code | Description
> TIBEMS_INSUFFICIENT_BUFFER | The buffer is not large enough for the data. The return parameter actual_size indicates the size of the required buffer.

> See Also
> tibemsMsg_CreateFromBytes on page 30
> tibemsMsg_GetAsBytes on page 32
> tibemsMsg_GetByteSize on page 36
> tibemsMsg_GetBodyType
> Function
> Purpose
> Get the body type of a message.

> | Message body type is distinct from message type—even though they have similar names. Contrast tibemsMsg_GetType on page 52.

> C Declaration
> tibems_status tibemsMsg_GetBodyType(
> tibemsMsg message,
> tibemsMsgType* type );
> COBOL Call
> CALL "tibemsMsg_GetBodyType"
> USING BY VALUE message,
> BY REFERENCE type,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Get the body type of this message.
> type | The function stores the body type in this location.

> See Also
> Body Types
> tibemsMsgType on page 137
> tibemsMsg_GetByteSize
> Function
> Purpose
> Computes the size of the byte sequence representation of the message.
> C Declaration
> tibems_status tibemsMsg_GetByteSize(
> tibemsMsg message,
> tibems_int* size );
> COBOL Call
> CALL "tibemsMsg_GetByteSize"
> USING BY VALUE message,
> BY REFERENCE size,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Compute the size of this message.
> size | The function stores the message size in this location.

> Remarks
> This call computes the size of a message in bytes. This measurement accounts for the actual space that the wire format message occupies, including its header, properties, and body data. (It does not include allocated storage that remains unused.)
> Before calling tibemsMsg_GetAsBytesCopy, use this call to measure the size of a message, then allocate sufficient space to store a copy.
> You can also use this call to measure network throughput, or to limit a program’s output rate (also called throttling).
> Deprecated Form
> tibems_int tibemsMsg_ByteSize(
> tibemsMsg message );

> | Do not use this deprecated form. It will become obsolete in a future release.

> See Also
> tibemsMsg_GetAsBytesCopy on page 33
> tibemsMsg_GetCorrelationID
> Function
> Purpose
> Get the correlation ID header of a message.
> C Declaration
> tibems_status tibemsMsg_GetCorrelationID(
> tibemsMsg message,
> const char** value );
> COBOL Call
> CALL "tibemsMsg_GetCorrelationID"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.

> | message and value have usage pointer.

> Parameters

> Parameter | Description
> message | Get the correlation ID of this message.
> value | The function stores the correlation ID in this location.

> Remarks
> Correlation ID refers to a related message. For example, when a consumer responds to a request message by sending a reply, it can set the correlation ID of the reply to indicate the request message.
> The JMS specification allows three categories of values for the correlation ID property:

> ● | Message ID A message ID is a unique string that the provider assigns to a message. Programs can use these IDs to correlate messages. For example, a program can link a response to a request by setting the correlation ID of a response message to the message ID of the corresponding request message.

> Message ID strings begin with the prefix ID: (which is reserved for this purpose).

> ● | String Programs can also correlate messages using arbitrary strings, with semantics determined by the application.

> These strings must not begin with the prefix ID: (which is reserved for message IDs).

> ● | Byte Array This implementation does not support byte array values for the correlation ID property. The JMS specification does not require support.

> See Also
> tibemsMsg_GetMessageID on page 43
> tibemsMsg_SetCorrelationID on page 57
> tibemsMsg_GetDeliveryMode
> Function
> Purpose
> Get the delivery mode header from a message.
> C Declaration
> tibems_status tibemsMsg_GetDeliveryMode(
> tibemsMsg message,
> tibemsDeliveryMode* value );
> COBOL Call
> CALL "tibemsMsg_GetDeliveryMode"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Get the delivery mode from this message.
> value | The function stores the delivery mode in this location.

> Remarks
> Delivery mode is a header property of message objects.
> See Also
> tibemsDeliveryMode on page 127
> tibemsMsg_SetDeliveryMode on page 59
> tibemsMsg_GetDestination
> Function
> Purpose
> Get the destination header from a message.
> C Declaration
> tibems_status tibemsMsg_GetDestination(
> tibemsMsg message,
> tibemsDestination* value );
> COBOL Call
> CALL "tibemsMsg_GetDestination"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.

> | message and value have usage pointer.

> Parameters

> Parameter | Description
> message | Get the destination from this message.
> value | The function stores the destination in this location.

> Remarks
> Sending calls record the destination (queue or topic) of the message in this header (ignoring and overwriting any existing value). The value is based on either a property of the producer, or on a parameter to the send call.
> Listeners that consume messages from several destinations can use this property to determine the actual destination of a message.
> See Also
> tibemsDestination on page 144
> tibemsMsg_SetDestination on page 60
> tibemsMsg_GetEncoding
> Function
> Purpose
> Get the character encoding header from a message.
> C Declaration
> tibems_status tibemsMsg_GetEncoding(
> const tibemsMsg message,
> const char** value );
> COBOL Call
> CALL "tibemsMsg_GetEncoding"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.

> | message and value have usage pointer.

> Parameters

> Parameter | Description
> message | Get the character encoding from this message.
> value | The function stores the character encoding in this location.

> Remarks
> This call extends the JMS specification.
> This encoding applies to all strings in message bodies (names and values), and properties (names and values). It does not apply to header names nor values. The functions tibemsBytesMsg_ReadUTF and tibemsBytesMsg_WriteUTF are exempt from message encoding settings.
> See Also
> Strings and Character Encodings
> tibemsMsg_SetEncoding on page 61
> tibemsMsg_GetExpiration
> Function
> Purpose
> Get the expiration header from a message.
> C Declaration
> tibems_status tibemsMsg_GetExpiration(
> tibemsMsg message,
> tibems_long* value );
> COBOL Call
> CALL "tibemsMsg_GetExpiration"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Get the expiration from this message.
> value | The function stores the expiration in this location.

> Remarks
> Sending calls record the expiration time (in milliseconds) of the message in this field:

> ● | If the time-to-live is non-zero, the expiration is the sum of that time-to-live and the sending client’s current time (GMT).

> ● | If the time-to-live is zero, then expiration is also zero—indicating that the message never expires.

> The server discards a message when its expiration time has passed. However, the JMS specification does not guarantee that clients do not receive expired messages.
> See Also
> tibemsMsg_SetExpiration on page 62
> tibemsMsgProducer_GetTimeToLive on page 183
> tibemsMsg_GetMessageID
> Function
> Purpose
> Get the message ID header from a message.
> C Declaration
> tibems_status tibemsMsg_GetMessageID(
> tibemsMsg message,
> const char** value );
> COBOL Call
> CALL "tibemsMsg_GetMessageID"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.

> | message and value have usage pointer.

> Parameters

> Parameter | Description
> message | Get the message ID from this message.
> value | The function stores the message ID in this location.

> Remarks
> Sending calls assign a unique ID to each message, and record it in this header.
> All message ID values start with the 3-character prefix ID: (which is reserved for this purpose).
> Applications that do not require message IDs can reduce overhead costs by disabling IDs; see tibemsMsgProducer_SetDisableMessageID on page 188. When the producer disables IDs, the value of this header is null.
> See Also
> tibemsMsg_GetCorrelationID on page 37
> tibemsMsg_SetMessageID on page 63
> tibemsMsgProducer_SetDisableMessageID on page 188
> tibemsMsg_GetPriority
> Function
> Purpose
> Get the priority header from a message.
> C Declaration
> tibems_status tibemsMsg_GetPriority(
> tibemsMsg message,
> tibems_int* value );
> COBOL Call
> CALL "tibemsMsg_GetPriority"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Get the priority from this message.
> value | The function stores the priority in this location.

> Remarks
> Sending calls record the priority of a message in this header, based on either a property of the producer, or on a parameter to the send call.
> The JMS specification defines ten levels of priority value, from zero (lowest priority) to 9 (highest priority). The specification suggests that clients consider 0–4 as gradations of normal priority, and priorities 5–9 as gradations of expedited priority.
> Priority affects the order in which the server delivers messages to consumers (higher values first). The JMS specification does not require all providers to implement priority ordering of messages. (EMS supports priorities, but other JMS providers might not.)
> See Also
> tibemsMsg_SetPriority on page 64
> tibemsMsgProducer_Send on page 184
> tibemsMsgProducer_SetPriority on page 192
> tibemsMsg_Get Property
> Function
> Purpose
> Get the value of a message property.
> C Declaration
> tibems_status tibemsMsg_GetProperty(
> tibemsMsg message,
> const char* name,
> tibemsMsgField* value );
> tibems_status tibemsMsg_GetBooleanProperty(
> tibemsMsg message,
> const char* name,
> tibems_bool* value );
> tibems_status tibemsMsg_GetByteProperty(
> tibemsMsg message,
> const char* name,
> tibems_byte* value );
> tibems_status tibemsMsg_GetDoubleProperty(
> tibemsMsg message,
> const char* name,
> tibems_double* value );
> tibems_status tibemsMsg_GetFloatProperty(
> tibemsMsg message,
> const char* name,
> tibems_float* value );
> tibems_status tibemsMsg_GetIntProperty(
> tibemsMsg message,
> const char* name,
> tibems_int* value );
> tibems_status tibemsMsg_GetLongProperty(
> tibemsMsg message,
> const char* name,
> tibems_long* value );
> tibems_status tibemsMsg_GetShortProperty(
> tibemsMsg message,
> const char* name,
> tibems_short* value );
> tibems_status tibemsMsg_GetStringProperty(
> tibemsMsg message,
> const char* name,
> char** value );
> COBOL Call
> CALL "tibemsMsg_GetProperty"
> USING BY VALUE message,
> BY REFERENCE name,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsMsg_GetBooleanProperty"
> USING BY VALUE message,
> BY REFERENCE name,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsMsg_GetByteProperty"
> USING BY VALUE message,
> BY REFERENCE name,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsMsg_GetDoubleProperty"
> USING BY VALUE message,
> BY REFERENCE name,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsMsg_GetFloatProperty"
> USING BY VALUE message,
> BY REFERENCE name,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsMsg_GetIntProperty"
> USING BY VALUE message,
> BY REFERENCE name,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsMsg_GetLongProperty"
> USING BY VALUE message,
> BY REFERENCE name,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsMsg_GetShortProperty"
> USING BY VALUE message,
> BY REFERENCE name,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsMsg_GetStringProperty"
> USING BY VALUE message,
> BY REFERENCE name,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer. value has usage pointer only in tibemsMsg_GetStringProperty (but not in the other calls documented in this group).

> Parameters

> Parameter | Description
> message | Get a property from this message.
> name | Get the property with this name (case sensitive). Property names must obey the JMS rules for a message selector identifier (see Message Selectors). Property names must not be null, and must not be empty strings.
> value | The call stores the value in this location.

> Remarks
> The JMS specification defines eight calls to get properties with different value types—converting between compatible types. All of these functions convert property values to the corresponding type (if possible).

> Status Code | Description
> TIBEMS_CONVERSION_FAILED | The actual type of the property is not compatible with the requested type.
> TIBEMS_NOT_FOUND | The property is not set in this message.

> See Also
> tibemsMsg_Set Property
> tibemsMsg_GetPropertyNames
> Function
> Purpose
> Get a list of property names from a message.
> C Declaration
> tibems_status tibemsMsg_GetPropertyNames(
> tibemsMsg message,
> tibemsMsgEnum* enumeration );
> COBOL Call
> CALL "tibemsMsg_GetPropertyNames"
> USING BY VALUE message,
> BY REFERENCE enumeration,
> RETURNING tibems-status
> END-CALL.

> | message and enumeration have usage pointer.

> Parameters

> Parameter | Description
> message | Get the property names from this message.
> enumeration | The function stores the property names in this location.

> See Also
> tibemsMsgEnum on page 129
> tibemsMsg_GetRedelivered
> Function
> Purpose
> Get the redelivered header from a message.
> C Declaration
> tibems_status tibemsMsg_GetRedelivered(
> tibemsMsg message,
> tibems_bool* value );
> COBOL Call
> CALL "tibemsMsg_GetRedelivered"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Get the redelivered indicator from this message.
> value | The function stores the redelivered indicator in this location.

> Remarks
> The server sets this header to indicate whether a message might duplicate a previously delivered message:

> ● | false—The server has not previously attempted to deliver this message to the consumer.

> ● | true—It is likely, but not guaranteed, that this message was delivered earlier but that its receipt was not acknowledged at that time.

> See Also
> tibemsMsg_SetRedelivered on page 68
> tibemsMsg_GetReplyTo
> Function
> Purpose
> Get the reply-to header from a message.
> C Declaration
> tibems_status tibemsMsg_GetReplyTo(
> tibemsMsg message,
> tibemsDestination* value );
> COBOL Call
> CALL "tibemsMsg_GetReplyTo"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.

> | message and value have usage pointer.

> Parameters

> Parameter | Description
> message | Get the reply-to header from this message.
> value | The function stores the reply-to header in this location.

> Remarks
> Sending clients can set this header to request that recipients reply to the message:

> ● | When the value is a destination object, recipients can send replies to that destination. Such a message is called a request.

> ● | When the value is null, the sender does not expect a reply.

> When sending a reply, clients can refer to the corresponding request by setting the correlation ID field.
> See Also
> tibemsMsg_SetCorrelationID on page 57
> tibemsMsg_SetReplyTo on page 69
> tibemsMsg_GetTimestamp
> Function
> Purpose
> Get the timestamp header from a message.
> C Declaration
> tibems_status tibemsMsg_GetTimestamp(
> tibemsMsg message,
> tibems_long* value );
> COBOL Call
> CALL "tibemsMsg_GetTimestamp"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Get the timestamp from this message.
> value | The function stores the timestamp in this location.

> Remarks
> Sending calls record a UTC timestamp in this header, indicating the approximate time that the server accepted the message.
> The value is in milliseconds since January 1, 1970 (as in Java).
> Applications that do not require timestamps can reduce overhead costs by disabling timestamps; see tibemsMsgProducer_SetDisableMessageTimestamp on page 189. When the producer disables timestamps, the value of this header is zero.
> See Also
> tibemsMsg_SetTimestamp on page 70
> tibemsMsgProducer_SetDisableMessageTimestamp on page 189
> tibemsMsg_GetType
> Function
> Purpose
> Get the type header of a message.

> | Message type is distinct from message body type—even though they have similar names. Contrast tibemsMsg_GetBodyType on page 35.

> C Declaration
> tibems_status tibemsMsg_GetType(
> tibemsMsg message,
> const char** value );
> COBOL Call
> CALL "tibemsMsg_GetType"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.

> | message and value have usage pointer.

> Parameters

> Parameter | Description
> message | Get the type header of this message.
> value | The function stores the type in this location.

> Remarks
> Some JMS providers use a message repository to store message type definitions. Client programs can store a body type that references a definition in the repository. EMS supports this header, but does not use it.
> The JMS specification does not define a standard message definition repository, nor does it define a naming policy for message type definitions.
> Some providers require message type definitions for each application message. To ensure compatibility with such providers, client programs can set this header, even if the client application does not use it.
> To ensure portability, clients can set this header with symbolic values (rather than literals), and configure them to match the provider’s repository.
> See Also
> tibemsMsg_SetType on page 71
> tibemsMsg_MakeWriteable
> Function
> Purpose
> Make a message writeable.
> C Declaration
> tibems_status tibemsMsg_MakeWriteable(
> tibemsMsg message );
> COBOL Call
> CALL "tibemsMsg_MakeWriteable"
> USING BY VALUE message,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Make this message writeable.

> tibemsMsg_Print
> Function
> Purpose
> Print a message.
> C Declaration
> void tibemsMsg_Print(
> tibemsMsg message );
> COBOL Call
> CALL "tibemsMsg_Print"
> USING BY VALUE message,
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Print this message.

> Remarks
> This call prints a string that includes the body type, headers (name-value pairs), properties (name-value pairs), and body content.
> tibemsMsg_Print prints the message to stdout.
> See Also
> tibemsMsg_PrintToBuffer on page 55
> tibemsMsg_PrintToBuffer
> Function
> Purpose
> Prints a message into a buffer.
> C Declaration
> tibems_status tibemsMsg_PrintToBuffer(
> tibemsMsg message,
> char* buffer,
> tibems_int maxlen );
> COBOL Call
> CALL "tibemsMsg_PrintToBuffer"
> USING BY VALUE message,
> BY REFERENCE buffer,
> BY VALUE maxlen,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Print this message.
> buffer | Location to store the string representation of the message.
> maxlen | The size of the buffer.

> Remarks
> This call prints a string that includes the body type, headers (name-value pairs), properties (name-value pairs), and body content.
> tibemsMsg_PrintToBuffer prints the message to a buffer.

> Status Code | Description
> TIBEMS_INSUFFICIENT_BUFFER | The buffer is too small to hold the data.

> See Also
> tibemsMsg_Print on page 54
> tibemsMsg_PropertyExists
> Function
> Purpose
> Test whether a named property has been set on a message.
> C Declaration
> tibems_status tibemsMsg_PropertyExists(
> tibemsMsg message,
> const char* name,
> tibems_bool* result );
> COBOL Call
> CALL "tibemsMsg_PropertyExists"
> USING BY VALUE message,
> BY REFERENCE name,
> BY REFERENCE result,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Test this message for the property.
> name | Test whether the message has a property with this name.
> result | The function stores the boolean result of the test in this location:
> ● | TIBEMS_TRUE if the property has a value on the message
> ● | TIBEMS_FALSE otherwise

> tibemsMsg_SetCorrelationID
> Function
> Purpose
> Set the correlation ID header of a message.
> C Declaration
> tibems_status tibemsMsg_SetCorrelationID(
> tibemsMsg message,
> const char* value );
> COBOL Call
> CALL "tibemsMsg_SetCorrelationID"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Set the correlation ID of this message.
> value | Set the correlation ID to this value.

> Remarks
> Correlation ID refers to a related message. For example, when a consumer responds to a request message by sending a reply, it can set the correlation ID of the reply to indicate the request message.
> The JMS specification allows three categories of values for the correlation ID property:

> ● | Message ID A message ID is a unique string that the provider assigns to a message. Programs can use these IDs to correlate messages. For example, a program can link a response to a request by setting the correlation ID of a response message to the message ID of the corresponding request message.

> Message ID strings begin with the prefix ID: (which is reserved for this purpose).

> ● | String Programs can also correlate messages using arbitrary strings, with semantics determined by the application.

> These strings must not begin with the prefix ID: (which is reserved for message IDs).

> ● | Byte Array This implementation does not support byte array values for the correlation ID property. The JMS specification does not require support.

> See Also
> tibemsMsg_GetCorrelationID on page 37
> tibemsMsg_GetMessageID on page 43
> tibemsMsg_SetDeliveryMode
> Function
> Purpose
> Set the delivery mode header of a message.
> C Declaration
> tibems_status tibemsMsg_SetDeliveryMode(
> tibemsMsg message,
> tibemsDeliveryMode value );
> COBOL Call
> CALL "tibemsMsg_SetDeliveryMode"
> USING BY VALUE message,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Set the delivery mode of this message.
> value | Set the delivery mode to this value.

> Remarks
> Sending calls set the delivery mode header automatically. The JMS specification defines this call for symmetry.
> See Also
> tibemsDeliveryMode on page 127
> tibemsMsg_GetDeliveryMode on page 39
> tibemsMsg_SetDestination
> Function
> Purpose
> Set the destination header of a message.
> C Declaration
> tibems_status tibemsMsg_SetDestination(
> tibemsMsg message,
> tibemsDestination value );
> COBOL Call
> CALL "tibemsMsg_SetDestination"
> USING BY VALUE message,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.

> | message and value have usage pointer.

> Parameters

> Parameter | Description
> message | Set the destination of this message.
> value | Set the destination to this value.

> Remarks
> Sending calls set the delivery mode header automatically. The JMS specification defines this call for symmetry.
> Sending calls record the destination (queue or topic) of the message in this header (ignoring and overwriting any existing value). The value is based on either a property of the producer, or on a parameter to the send call.
> See Also
> tibemsDestination on page 144
> tibemsMsg_GetDestination on page 40
> tibemsMsgProducer_Send on page 184
> tibemsMsgProducer_GetDestination on page 178
> tibemsMsg_SetEncoding
> Function
> Purpose
> Set the character encoding header of a message.
> C Declaration
> tibems_status tibemsMsg_SetEncoding(
> tibemsMsg message,
> const char* value );
> COBOL Call
> CALL "tibemsMsg_SetEncoding"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Set the character encoding of this message.
> value | Set the character encoding to this value. For a list of standard encoding names, see www.iana.org.

> Remarks
> This call extends the JMS specification.
> Programs can set the encoding for individual messages.
> This encoding applies to all strings in message bodies (names and values), and properties (names and values). It does not apply to header names nor values. The functions tibemsBytesMsg_ReadUTF and tibemsBytesMsg_WriteUTF are exempt from message encoding settings.
> See Also
> Strings and Character Encodings
> tibemsMsg_GetEncoding on page 41
> tibemsMsg_SetExpiration
> Function
> Purpose
> Set the expiration header of a message.
> C Declaration
> tibems_status tibemsMsg_SetExpiration(
> tibemsMsg message,
> tibems_long value );
> COBOL Call
> CALL "tibemsMsg_SetExpiration"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Set the expiration of this message.
> value | Set the expiration to this value.

> Remarks
> Sending calls set the expiration header automatically. The JMS specification defines this call for symmetry.
> Sending calls record the expiration time (in milliseconds) of the message in this field:

> ● | If the time-to-live is non-zero, the expiration is the sum of that time-to-live and the sending client’s current time (GMT).

> ● | If the time-to-live is zero, then expiration is also zero—indicating that the message never expires.

> The server discards a message when its expiration time has passed. However, the JMS specification does not guarantee that clients do not receive expired messages.
> See Also
> tibemsMsg_GetExpiration on page 42
> tibemsMsgProducer_GetTimeToLive on page 183
> tibemsMsgProducer_SetTimeToLive on page 193
> tibemsMsg_SetMessageID
> Function
> Purpose
> Set the message ID header of a message.
> C Declaration
> tibems_status tibemsMsg_SetMessageID(
> tibemsMsg message,
> const char* value );
> COBOL Call
> CALL "tibemsMsg_SetMessageID"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Set the message ID of this message.
> value | Set the message ID to this value.

> Remarks
> Sending calls set the message ID header automatically. The JMS specification defines this call for symmetry.
> Sending calls assign a unique ID to each message, and record it in this header.
> All message ID values start with the 3-character prefix ID: (which is reserved for this purpose).
> Applications that do not require message IDs can reduce overhead costs by disabling IDs; see tibemsMsgProducer_SetDisableMessageID on page 188. When the producer disables IDs, the value of this header is null.
> See Also
> tibemsMsg_GetCorrelationID on page 37
> tibemsMsg_GetMessageID on page 43
> tibemsMsg_SetCorrelationID on page 57
> tibemsMsgProducer_SetDisableMessageID on page 188
> tibemsMsg_SetPriority
> Function
> Purpose
> Set the priority header of a message.
> C Declaration
> tibems_status tibemsMsg_SetPriority(
> tibemsMsg message,
> tibems_int value );
> COBOL Call
> CALL "tibemsMsg_SetPriority"
> USING BY VALUE message,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Set the priority of this message.
> value | Set the priority to this value.

> Remarks
> Sending calls set the priority header automatically. The JMS specification defines this call for symmetry.
> Sending calls record the priority of a message in this header, based on either a property of the producer, or on a parameter to the send call.
> The JMS specification defines ten levels of priority value, from zero (lowest priority) to 9 (highest priority). The specification suggests that clients consider 0–4 as gradations of normal priority, and priorities 5–9 as gradations of expedited priority.
> Priority affects the order in which the server delivers messages to consumers (higher values first). The JMS specification does not require all providers to implement priority ordering of messages. (EMS supports priorities, but other JMS providers might not.)
> See Also
> tibemsMsg_GetPriority on page 44
> tibemsMsgProducer_GetPriority on page 182
> tibemsMsgProducer_SetPriority on page 192
> tibemsMsg_Set Property
> Function
> Purpose
> Set the value of a message property.
> C Declaration
> tibems_status tibemsMsg_SetBooleanProperty(
> tibemsMsg message,
> const char* name,
> tibems_bool value );
> tibems_status tibemsMsg_SetByteProperty(
> tibemsMsg message,
> const char* name,
> tibems_byte value );
> tibems_status tibemsMsg_SetDoubleProperty(
> tibemsMsg message,
> const char* name,
> tibems_double value );
> tibems_status tibemsMsg_SetFloatProperty(
> tibemsMsg message,
> const char* name,
> tibems_float value );
> tibems_status tibemsMsg_SetIntProperty(
> tibemsMsg message,
> const char* name,
> tibems_int value );
> tibems_status tibemsMsg_SetLongProperty(
> tibemsMsg message,
> const char* name,
> tibems_long value );
> tibems_status tibemsMsg_SetShortProperty(
> tibemsMsg message,
> const char* name,
> tibems_short value );
> tibems_status tibemsMsg_SetStringProperty(
> tibemsMsg message,
> const char* name,
> const char* value );
> COBOL Call
> CALL "tibemsMsg_SetBooleanProperty"
> USING BY VALUE message,
> BY REFERENCE name,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsMsg_SetByteProperty"
> USING BY VALUE message,
> BY REFERENCE name,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsMsg_SetDoubleProperty"
> USING BY VALUE message,
> BY REFERENCE name,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsMsg_SetFloatProperty"
> USING BY VALUE message,
> BY REFERENCE name,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsMsg_SetIntProperty"
> USING BY VALUE message,
> BY REFERENCE name,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsMsg_SetLongProperty"
> USING BY VALUE message,
> BY REFERENCE name,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsMsg_SetShortProperty"
> USING BY VALUE message,
> BY REFERENCE name,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsMsg_SetStringProperty"
> USING BY VALUE message,
> BY REFERENCE name,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer. value has usage pointer only in tibemsMsg_SetStringProperty (but not in the other calls documented in this group).

> Parameters

> Parameter | Description
> message | Set a property on this message. Property names must obey the JMS rules for a message selector identifier (see Message Selectors). Property names must not be null, and must not be empty strings.
> name | Set a property with this name. Property names must obey the JMS rules for a message selector identifier (see Message Selectors). Property names must not be null, and must not be empty strings.
> value | Set the property to this value.

> Remarks
> The JMS specification defines eight calls to set properties with different primitive value types.

> Status Code | Description
> TIBEMS_MSG_NOT_WRITEABLE | The message is read-only.

> See Also
> tibemsMsg_Get Property
> tibemsMsg_SetRedelivered
> Function
> Purpose
> Set the redelivered header of a message.
> C Declaration
> tibems_status tibemsMsg_SetRedelivered(
> tibemsMsg message,
> tibems_bool value );
> COBOL Call
> CALL "tibemsMsg_SetRedelivered"
> USING BY VALUE message,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Set the redelivered indicator of this message.
> value | Set the redelivered indicator to this value.

> Remarks
> Sending calls set the redelivered header automatically. The JMS specification defines this call for symmetry.
> The server sets this header to indicate whether a message might duplicate a previously delivered message:

> ● | false—The server has not previously attempted to deliver this message to the consumer.

> ● | true—It is likely (but not guaranteed) that the server has previously attempted to deliver this message to the consumer, but the consumer did not return timely acknowledgement.

> See Also
> tibemsMsg_GetRedelivered on page 49
> tibemsMsg_SetReplyTo
> Function
> Purpose
> Set the reply-to header of a message.
> C Declaration
> tibems_status tibemsMsg_SetReplyTo(
> tibemsMsg message,
> tibemsDestination value );
> COBOL Call
> CALL "tibemsMsg_SetReplyTo"
> USING BY VALUE message,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.

> | message and value have usage pointer.

> Parameters

> Parameter | Description
> message | Set the reply-to header of this message.
> value | Set the reply-to header to this value.

> Remarks
> Sending clients can set this header to request that recipients reply to the message:

> ● | When the value is a destination object, recipients can send replies to that destination. Such a message is called a request.

> ● | When the value is null, the sender does not expect a reply.

> When sending a reply, clients can refer to the corresponding request by setting the correlation ID field.
> See Also
> tibemsMsg_GetReplyTo on page 50
> tibemsMsg_SetCorrelationID on page 57
> tibemsMsg_SetTimestamp
> Function
> Purpose
> Set the timestamp header of a message.
> C Declaration
> tibems_status tibemsMsg_SetTimestamp(
> tibemsMsg message,
> tibems_long value );
> COBOL Call
> CALL "tibemsMsg_SetTimestamp"
> USING BY VALUE message,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Set the timestamp of this message.
> value | Set the timestamp to this value.

> Remarks
> Sending calls set the timestamp header automatically. The JMS specification defines this call for symmetry.
> Sending calls record a UTC timestamp in this header, indicating the approximate time that the server accepted the message.
> The value is in milliseconds since January 1, 1970 (as in Java).
> Applications that do not require timestamps can reduce overhead costs by disabling timestamps; see tibemsMsgProducer_SetDisableMessageTimestamp on page 189. When the producer disables timestamps, the value of this header is zero.
> See Also
> tibemsMsg_GetTimestamp on page 51
> tibemsMsgProducer_SetDisableMessageTimestamp on page 189
> tibemsMsg_SetType
> Function
> Purpose
> Set the type header of a message.

> | Message type is distinct from message body type—even though they have similar names. Contrast tibemsMsg_GetBodyType on page 35.

> C Declaration
> tibems_status tibemsMsg_SetType(
> tibemsMsg message,
> const char* value );
> COBOL Call
> CALL "tibemsMsg_SetType"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Set the type header of this message.
> value | Set the type to this value.

> Remarks
> Some JMS providers use a message repository to store message type definitions. Client programs can store a body type that references a definition in the repository. EMS supports this header, but does not use it.
> The JMS specification does not define a standard message definition repository, nor does it define a naming policy for message type definitions.
> Some providers require message type definitions for each application message. To ensure compatibility with such providers, client programs can set this header, even if the client application does not use it.
> To ensure portability, clients can set this header with symbolic values (rather than literals), and configure them to match the provider’s repository.
> See Also
> tibemsMsg_GetType on page 52

Copyright © TIBCO Software Inc. All Rights Reserved.