Table 7 Message Constants When neither the sending call nor the producer supplies a delivery mode, this default applies. When neither the sending call nor the producer supplies a priority, this default applies. When neither the sending call nor the producer supplies a priority, this default applies. The default value, zero, indicates that messages do not expire.tibems_status tibemsMsg_Acknowledge(tibemsMsg message );
message has usage pointer.
Acknowledge this message (but for the actual behavior of this call, see the Remarks below).
• 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.)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.It is illegal to call this function after closing the session, the connection or the consumer through which the message arrived.tibems_status tibemsMsg_ClearBody(tibemsMsg message );
message has usage pointer.
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.tibems_status tibemsMsg_ClearProperties(tibemsMsg message );
message has usage pointer.
tibems_status tibemsMsg_Create(tibemsMsg* message );
message has usage pointer.
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.tibems_status tibemsMsg_CreateCopy(const tibemsMsg message,tibemsMsg* copy );
message and copy have usage pointer.
The copy is completely independent of the original message. Pointer data in fields are independent copies of the original values.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.tibems_status tibemsMsg_CreateFromBytes(tibemsMsg* message,
message has usage pointer.
This data buffer represents the message in EMS wire format. To produce this type of buffer, use either tibemsMsg_GetAsBytes or tibemsMsg_GetAsBytesCopy.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 newly created message is read-only; to enable modification without erasing the content, call tibemsMsg_MakeWriteable.tibems_status tibemsMsg_Destroy(tibemsMsg message );
message has usage pointer.
tibems_status tibemsMsg_GetAsBytes(const tibemsMsg message,tibems_int* actual_size );
message and bytes have usage pointer.
The function allocates a byte sequence, and stores a pointer to it in this location. 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.tibems_status tibemsMsg_GetAsBytesCopy(const tibemsMsg message,tibems_int avail_size,tibems_int* actual_size );
message has usage pointer.
Your program must supply storage suitable for a byte sequence. The function stores the byte sequence in this location. 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 buffer is not large enough for the data. The return parameter actual_size indicates the size of the required buffer.
tibems_status tibemsMsg_GetBodyType(tibemsMsg message,tibemsMsgType* type );
message has usage pointer.
tibems_status tibemsMsg_GetByteSize(tibemsMsg message,tibems_int* size );
message has usage pointer.
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 Formtibems_int tibemsMsg_ByteSize(tibemsMsg message );
tibems_status tibemsMsg_GetCorrelationID(tibemsMsg message,
message and value have usage pointer.
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.
• 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.
• Byte Array This implementation does not support byte array values for the correlation ID property. The JMS specification does not require support.tibems_status tibemsMsg_GetDeliveryMode(tibemsMsg message,tibemsDeliveryMode* value );
message has usage pointer.
tibems_status tibemsMsg_GetDestination(tibemsMsg message,tibemsDestination* value );
message and value have usage pointer.
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.tibems_status tibemsMsg_GetEncoding(const tibemsMsg message,
message and value have usage pointer.
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.tibems_status tibemsMsg_GetExpiration(tibemsMsg message,tibems_long* value );
message has usage pointer.
• 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.tibems_status tibemsMsg_GetMessageID(tibemsMsg message,
message and value have usage pointer.
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.tibems_status tibemsMsg_GetPriority(tibemsMsg message,tibems_int* value );
message has usage pointer.
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.)tibems_status tibemsMsg_GetProperty(tibemsMsg message,tibemsMsgField* value );tibems_status tibemsMsg_GetBooleanProperty(tibemsMsg message,tibems_bool* value );tibems_status tibemsMsg_GetByteProperty(tibemsMsg message,tibems_byte* value );tibems_status tibemsMsg_GetDoubleProperty(tibemsMsg message,tibems_double* value );tibems_status tibemsMsg_GetFloatProperty(tibemsMsg message,tibems_float* value );tibems_status tibemsMsg_GetIntProperty(tibemsMsg message,tibems_int* value );tibems_status tibemsMsg_GetLongProperty(tibemsMsg message,tibems_long* value );tibems_status tibemsMsg_GetShortProperty(tibemsMsg message,tibems_short* value );tibems_status tibemsMsg_GetStringProperty(tibemsMsg message,
message has usage pointer.value has usage pointer only in tibemsMsg_GetStringProperty (but not in the other calls documented in this group).
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. 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).
The actual type of the property is not compatible with the requested type. tibems_status tibemsMsg_GetPropertyNames(tibemsMsg message,tibemsMsgEnum* enumeration );
message and enumeration have usage pointer.
tibems_status tibemsMsg_GetRedelivered(tibemsMsg message,tibems_bool* value );
message has usage pointer.
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.tibems_status tibemsMsg_GetReplyTo(tibemsMsg message,tibemsDestination* value );
message and value have usage pointer.
• When the value is a destination object, recipients can send replies to that destination. Such a message is called a request.When sending a reply, clients can refer to the corresponding request by setting the correlation ID field.tibems_status tibemsMsg_GetTimestamp(tibemsMsg message,tibems_long* value );
message has usage pointer.
Sending calls record a UTC timestamp in this header, indicating the approximate time that the server accepted the message.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.
tibems_status tibemsMsg_GetType(tibemsMsg message,
message and value have usage pointer.
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.tibems_status tibemsMsg_MakeWriteable(tibemsMsg message );
message has usage pointer.
tibemsMsg message );
message has usage pointer.
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.tibems_status tibemsMsg_PrintToBuffer(
message has usage pointer.
The size of the buffer.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.
tibems_status tibemsMsg_PropertyExists(tibemsMsg message,tibems_bool* result );
message has usage pointer.
• TIBEMS_TRUE if the property has a value on the message
• TIBEMS_FALSE otherwisetibems_status tibemsMsg_Recover(tibemsMsg message );
message has usage pointer.
When the application calls this function, TIBCO Enterprise Message Service puts this message back on the queue or topic and makes it available for redelivery. The JMSRedelivered header is set to true.This call is only legal for the TIBEMS_EXPLICIT_CLIENT_ACKNOWLEDGE and TIBEMS_EXPLICIT_CLIENT_DUPS_OK_ACKNOWLEDGE acknowledgement modes. In all other modes, this call returns TIBEMS_ILLEGAL_STATE.This function recovers only the specified message. To recover all unacknowledged messages from a session, use tibemsSession_Recover.It is illegal to call this function on an acknowledged message or on a message that is included in a transaction.Additionally, it is illegal to call this function twice on the same message, or again on a message that was previously recovered using tibemsSession_Recover.tibems_status tibemsMsg_SetCorrelationID(tibemsMsg message,
message has usage pointer.
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.
• 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.
• Byte Array This implementation does not support byte array values for the correlation ID property. The JMS specification does not require support.tibems_status tibemsMsg_SetDeliveryMode(tibemsMsg message,tibemsDeliveryMode value );
message has usage pointer.
Sending calls set the delivery mode header automatically. The JMS specification defines this call for symmetry.tibems_status tibemsMsg_SetDestination(tibemsMsg message,tibemsDestination value );
message and value have usage pointer.
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.tibems_status tibemsMsg_SetEncoding(tibemsMsg message,
message has usage pointer.
For a list of standard encoding names, see www.iana.org.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.tibems_status tibemsMsg_SetExpiration(tibemsMsg message,tibems_long value );
message has usage pointer.
Sending calls set the expiration header automatically. The JMS specification defines this call for symmetry.
• 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.tibems_status tibemsMsg_SetMessageID(tibemsMsg message,
message has usage pointer.
Sending calls set the message ID header automatically. The JMS specification defines this call for symmetry.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.tibems_status tibemsMsg_SetPriority(tibemsMsg message,tibems_int value );
message has usage pointer.
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.)tibemsMsg_Set Propertytibems_status tibemsMsg_SetBooleanProperty(tibemsMsg message,tibems_bool value );tibems_status tibemsMsg_SetByteProperty(tibemsMsg message,tibems_byte value );tibems_status tibemsMsg_SetDoubleProperty(tibemsMsg message,tibems_double value );tibems_status tibemsMsg_SetFloatProperty(tibemsMsg message,tibems_float value );tibems_status tibemsMsg_SetIntProperty(tibemsMsg message,tibems_int value );tibems_status tibemsMsg_SetLongProperty(tibemsMsg message,tibems_long value );tibems_status tibemsMsg_SetShortProperty(tibemsMsg message,tibems_short value );tibems_status tibemsMsg_SetStringProperty(tibemsMsg message,
message has usage pointer.value has usage pointer only in tibemsMsg_SetStringProperty (but not in the other calls documented in this group).
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. 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.
tibems_status tibemsMsg_SetRedelivered(tibemsMsg message,tibems_bool value );
message has usage pointer.
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.tibems_status tibemsMsg_SetReplyTo(tibemsMsg message,tibemsDestination value );
message and value have usage pointer.
• When the value is a destination object, recipients can send replies to that destination. Such a message is called a request.When sending a reply, clients can refer to the corresponding request by setting the correlation ID field.tibems_status tibemsMsg_SetTimestamp(tibemsMsg message,tibems_long value );
message has usage pointer.
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.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.
tibems_status tibemsMsg_SetType(tibemsMsg message,
message has usage pointer.
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.
Copyright © TIBCO Software Inc. All Rights Reserved.