Messages : tibemsMapMsg

tibemsMapMsg
Type
Purpose
A message containing a set of name-value pairs.
Related Types
tibemsMsg on page 21
Remarks
Messages with this body type contain several values, indexed by name.
 
Extensions
TIBCO Enterprise Message Service extends the JMS MapMessage and StreamMessage body types in two ways. These extensions allow TIBCO Enterprise Message Service to exchange messages with TIBCO Rendezvous and TIBCO SmartSockets programs, which have certain features not available within the JMS specification.
You can insert another MapMessage or StreamMessage instance as a submessage into a MapMessage or StreamMessage, generating a series of nested messages, instead of a flat message.
 
These extensions add considerable flexibility to the two body types. However, they are extensions and therefore not compliant with JMS specifications. Extended messages are tagged as extensions with the vendor property tag JMS_TIBCO_MSG_EXT.
For more information on message compatibility with Rendezvous messages, see Message Body in TIBCO Enterprise Message Service Release Notes.
tibemsMapMsg_Create
Function
Purpose
Create a map message.
C Declaration
tibems_status tibemsMapMsg_Create(
    tibemsMapMsg* message );
COBOL Call
CALL "tibemsMapMsg_Create"
USING BY REFERENCE message,
RETURNING tibems-status
END-CALL.
 
message has usage pointer.
Parameters
 
Remarks
This call creates a new map 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_Create on page 28
tibemsMsg_Destroy on page 31
tibemsMapMsg_Get
Function
Purpose
Get data values from a map message.
C Declaration
tibems_status tibemsMapMsg_GetBoolean(
    tibemsMapMsg message,
    const char* name,
    tibems_bool* value );
 
tibems_status tibemsMapMsg_GetByte(
    tibemsMapMsg message,
    const char* name,
    tibems_byte* value );
 
tibems_status tibemsMapMsg_GetBytes(
    tibemsMapMsg message,
    const char* name,
    void** bytes,
    tibems_uint* bytesSize );
 
tibems_status tibemsMapMsg_GetChar(
    tibemsMapMsg message,
    const char* name,
    tibems_wchar* value );
 
tibems_status tibemsMapMsg_GetDouble(
    tibemsMapMsg message,
    const char* name,
    tibems_double* value );
 
tibems_status tibemsMapMsg_GetField(
    tibemsMapMsg message,
    const char* name,
    tibemsMsgField* value );
 
tibems_status tibemsMapMsg_GetFloat(
    tibemsMapMsg message,
    const char* name,
    tibems_float* value );
 
tibems_status tibemsMapMsg_GetInt(
    tibemsMapMsg message,
    const char* name,
    tibems_int* value );
 
tibems_status tibemsMapMsg_GetLong(
    tibemsMapMsg message,
    const char* name,
    tibems_long* value );
 
tibems_status tibemsMapMsg_GetMapMsg(
    tibemsMapMsg message,
    const char* name,
    tibemsMapMsg* value );
 
tibems_status tibemsMapMsg_GetShort(
    tibemsMapMsg message,
    const char* name,
    tibems_short* value );
 
tibems_status tibemsMapMsg_GetString(
    tibemsMapMsg message,
    const char* name,
    const char** value );
COBOL Call
CALL "tibemsMapMsg_GetBoolean"
USING BY VALUE message,
BY REFERENCE name,
BY REFERENCE value,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_GetBytes"
USING BY VALUE message,
BY REFERENCE name,
BY REFERENCE bytes,
BY REFERENCE bytesSize,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_GetByte"
USING BY VALUE message,
BY REFERENCE name,
BY REFERENCE value,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_GetChar"
USING BY VALUE message,
BY REFERENCE name,
BY REFERENCE value,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_GetDouble"
USING BY VALUE message,
BY REFERENCE name,
BY REFERENCE value,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_GetField"
USING BY VALUE message,
BY REFERENCE name,
BY REFERENCE value,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_GetFloat"
USING BY VALUE message,
BY REFERENCE name,
BY REFERENCE value,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_GetInt"
USING BY VALUE message,
BY REFERENCE name,
BY REFERENCE value,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_GetLong"
USING BY VALUE message,
BY REFERENCE name,
BY REFERENCE value,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_GetMapMsg"
USING BY VALUE message,
BY REFERENCE name,
BY REFERENCE value,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_GetShort"
USING BY VALUE message,
BY REFERENCE name,
BY REFERENCE value,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_GetString"
USING BY VALUE message,
BY REFERENCE name,
BY REFERENCE value,
RETURNING tibems-status
END-CALL.
 
message and bytes have usage pointer.
value has usage pointer only in tibemsMapMsg_GetMapMsg and tibemsMapMsg_GetString (but not in the other calls documented in this group).
Parameters
 
For strings, nested messages and fields, the function stores (in this location) a pointer to the value within the message.
tibemsMapMsg_GetBytes stores a pointer to the byte sequence in this location.
tibemsMapMsg_GetBytes stores the length of the byte sequence in this location.
Remarks
The JMS specification defines these calls to extract data from the name-value pairs of a map message.
To get array values from a map message, call tibemsMapMsg_GetField, then extract the array value from the field; see tibemsMsgField on page 133.
When the message does not have a field set for the name, these calls return TIBEMS_NOT_FOUND.
tibemsMapMsg_GetMapNames
Function
Purpose
Get an enumeration of the field names in a map message.
C Declaration
tibems_status tibemsMapMsg_GetMapNames(
    tibemsMsg message,
    tibemsMsgEnum* enumeration );
COBOL Call
CALL "tibemsMapMsg_GetMapNames"
USING BY VALUE message,
BY REFERENCE enumeration,
RETURNING tibems-status
END-CALL.
 
message and enumeration have usage pointer.
Parameters
 
See Also
tibemsMsgEnum on page 130
tibemsMapMsg_ItemExists
Function
Purpose
Test if a named pair exists.
C Declaration
tibems_status tibemsMapMsg_ItemExists(
    tibemsMapMsg message,
    const char* name,
    tibems_bool* exists );
COBOL Call
CALL "tibemsMapMsg_ItemExists"
USING BY VALUE message,
BY REFERENCE name,
BY REFERENCE exists,
RETURNING tibems-status
END-CALL.
 
message has usage pointer.
Parameters
 
tibemsMapMsg—Set
Function
Purpose
Set a name-value pair in a map message.
Single Value
C Declarations
tibems_status tibemsMapMsg_SetBoolean(
    tibemsMapMsg message,
    const char* name,
    tibems_bool value );
 
tibems_status tibemsMapMsg_SetByte(
    tibemsMapMsg message,
    const char* name,
    tibems_byte value );
 
tibems_status tibemsMapMsg_SetChar(
    tibemsMapMsg message,
    const char* name,
    tibems_wchar value );
 
tibems_status tibemsMapMsg_SetDouble(
    tibemsMapMsg message,
    const char* name,
    tibems_double value );
 
tibems_status tibemsMapMsg_SetFloat(
    tibemsMapMsg message,
    const char* name,
    tibems_float value );
 
tibems_status tibemsMapMsg_SetInt(
    tibemsMapMsg message,
    const char* name,
    tibems_int value );
 
tibems_status tibemsMapMsg_SetLong(
    tibemsMapMsg message,
    const char* name,
    tibems_long value );
 
tibems_status tibemsMapMsg_SetShort(
    tibemsMapMsg message,
    const char* name,
    tibems_short value );
 
tibems_status tibemsMapMsg_SetString(
    tibemsMapMsg message,
    const char* name,
    const char* value );
Array
C Declarations
tibems_status tibemsMapMsg_SetDoubleArray(
    tibemsMapMsg message,
    const char* name,
    const tibems_double* value,
    tibems_uint count );
 
tibems_status tibemsMapMsg_SetFloatArray(
    tibemsMapMsg message,
    const char* name,
    const tibems_float* value,
    tibems_uint count );
 
tibems_status tibemsMapMsg_SetIntArray(
    tibemsMapMsg message,
    const char* name,
    const tibems_int* value,
    tibems_uint count );
 
tibems_status tibemsMapMsg_SetLongArray(
    tibemsMapMsg message,
    const char* name,
    const tibems_long* value,
    tibems_uint count );
 
tibems_status tibemsMapMsg_SetShortArray(
    tibemsMapMsg message,
    const char* name,
    const tibems_short* value,
    tibems_uint count );
Nested Message C Declarations
tibems_status tibemsMapMsg_SetMapMsg(
    tibemsMapMsg message,
    const char* name,
    tibemsMsg mapMsg,
    tibems_bool takeOwnership );
 
tibems_status tibemsMapMsg_SetStreamMsg(
    tibemsMsg message,
    const char* name,
    tibemsMsg streamMsg,
    tibems_bool takeOwnership);
COBOL Call
CALL "tibemsMapMsg_SetBoolean"
USING BY VALUE message,
BY REFERENCE name,
BY VALUE value,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_SetByte"
USING BY VALUE message,
BY REFERENCE name,
BY VALUE value,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_SetChar"
USING BY VALUE message,
BY REFERENCE name,
BY VALUE value,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_SetDouble"
USING BY VALUE message,
BY REFERENCE name,
BY VALUE value,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_SetDoubleArray"
USING BY VALUE message,
BY REFERENCE name,
BY REFERENCE value,
BY VALUE count,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_SetFloat"
USING BY VALUE message,
BY REFERENCE name,
BY VALUE value,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_SetFloatArray"
USING BY VALUE message,
BY REFERENCE name,
BY REFERENCE value,
BY VALUE count,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_SetInt"
USING BY VALUE message,
BY REFERENCE name,
BY VALUE value,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_SetIntArray"
USING BY VALUE message,
BY REFERENCE name,
BY REFERENCE value,
BY VALUE count,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_SetLong"
USING BY VALUE message,
BY REFERENCE name,
BY VALUE value,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_SetLongArray"
USING BY VALUE message,
BY REFERENCE name,
BY REFERENCE value,
BY VALUE count,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_SetMapMsg"
USING BY VALUE message,
BY REFERENCE name,
BY VALUE mapMsg,
BY VALUE tibems-Boolean,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_SetShort"
USING BY VALUE message,
BY REFERENCE name,
BY VALUE value,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_SetShortArray"
USING BY VALUE message,
BY REFERENCE name,
BY REFERENCE value,
BY VALUE count,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_SetStreamMsg"
USING BY VALUE message,
BY REFERENCE name,
BY VALUE streamMsg,
BY VALUE tibems-Boolean,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_SetString"
USING BY VALUE message,
BY REFERENCE name,
BY REFERENCE value,
RETURNING tibems-status
END-CALL.
 
message, streamMsg and mapMsg have usage pointer.
Parameters
 
tibemsMapMsg_SetMapMsg sets this map message as a nested value.
When this argument is TIBEMS_TRUE, the call increments the reference count of the nested message. This action prevents other calls from destroying the nested message improperly.
Remarks
The JMS specification defines functions to set name-value pairs in a MapMessage.
Extensions
Array functions and nested message functions extend the JMS specification. Use them only with SmartSockets or Rendezvous messages. Programs that use these extensions might be non-compliant, and cannot interoperate with other JMS providers.
See Also
tibemsMapMsg_Get
tibemsMapMsg_SetBytes on page 102
tibemsMapMsg_SetBytes
Function
Purpose
Set a byte array as a named value in a map message.
C Declaration
tibems_status tibemsMapMsg_SetBytes(
    tibemsMapMsg message,
    const char* name,
    void* bytes,
    tibems_uint bytesSize );
 
tibems_status tibemsMapMsg_SetReferencedBytes(
    tibemsMapMsg message,
    const char* name,
    void* bytes,
    tibems_uint bytesSize );
COBOL Call
CALL "tibemsMapMsg_SetBytes"
USING BY VALUE message,
BY REFERENCE name,
BY REFERENCE bytes,
BY VALUE bytesSize,
RETURNING tibems-status
END-CALL.
 
CALL "tibemsMapMsg_SetReferencedBytes"
USING BY VALUE message,
BY REFERENCE name,
BY REFERENCE bytes,
BY VALUE bytesSize,
RETURNING tibems-status
END-CALL.
 
message has usage pointer.
Parameters
 
Remarks
tibemsMapMsg_SetBytes copies the byte array into the map message field. The program may free the orignal byte array after this call returns.
tibemsMapMsg_SetReferencedBytes adds a reference to the byte array, but does not copy the bytes. When the byte array is very large, it can be more efficient to avoid making a copy. However, the program must not free nor modify the original byte array until after freeing the map message.