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

> Function | Description | Page
> tibemsMapMsg_Create | Create a map message. | 89
> tibemsMapMsg_Get | Get an enumeration of the field names in a map message. | 90
> tibemsMapMsg_GetMapNames | Create a map message. | 94
> tibemsMapMsg_ItemExists | Test if a named pair exists. | 95
> tibemsMapMsg—Set | Set a name-value pair in a map message. | 96

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

> ● | You can use arrays as well as primitive types for the values.

> 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

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

> 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

> Parameter | Description
> message | Get a value from this map message.
> name | Get the value associated with this name.
> value | For unitary values, the function copies the value into this location. For strings, nested messages and fields, the function stores (in this location) a pointer to the value within the message.
> bytes | tibemsMapMsg_GetBytes stores a pointer to the byte sequence in this location.
> bytesSize | 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 132.
> 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

> Parameter | Description
> message | Get the field names of this message.
> enumeration | The function stores a pointer to the enumeration in this location.

> See Also
> tibemsMsgEnum on page 129
> 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

> Parameter | Description
> message | Test in the body of this map message.
> name | Test for a pair with this name.
> exists | The function stores the boolean result of the test in this location.

> 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

> Parameter | Description
> message | Set the pair in the body of this map message.
> name | Set the pair with this name. Field names must not be null, and must not be empty strings.
> value | Associate this value with the name.
> count | Array functions set array values of this size (must be a positive number).
> mapMsg | tibemsMapMsg_SetMapMsg sets this map message as a nested value.
> takeOwnership | Nested message functions use this parameter to control ownership of nested messages. 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. We recommend that all calls supply TIBEMS_TRUE.

> 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 101
> 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

> Parameter | Description
> message | Set the name and value pair in the body of this map message.
> name | Set the pair with this name.
> bytes | Associate this byte array value with the name.
> bytesSize | Set a byte array value of this length.

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

Copyright © TIBCO Software Inc. All Rights Reserved.