Chapter 2 Messages : tibemsMsg

tibemsMsg
Type
Purpose
Messages carry information among EMS client programs.
Related Types
tibemsBytesMsg, tibemsMapMsg, tibemsObjectMsg, tibemsStreamMsg, tibemsTextMsg
 
 
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.
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
 
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.
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
 
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
 
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
 
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
 
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
 
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
 
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
 
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
 
Your program must supply storage suitable for a byte sequence. The function stores 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.
 
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.
 
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
 
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
 
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 );
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
 
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
 
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
 
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
 
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
 
Remarks
Sending calls record the expiration time (in milliseconds) of the message in this field:
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
 
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
 
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
 
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.
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).
 
The actual type of the property is not compatible with the requested type.
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
 
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
 
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
 
Remarks
Sending clients can set this header to request that recipients reply to the message:
 
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
 
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.
 
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
 
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
 
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
 
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
 
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.
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
 
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
 
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
 
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
 
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
 
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
 
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 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
 
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
 
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
 
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.
Remarks
The JMS specification defines eight calls to set properties with different primitive value types.
 
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
 
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
 
Remarks
Sending clients can set this header to request that recipients reply to the message:
 
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
 
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.
 
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
 
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