WebSphere Message Service Client for C/C++, Version 2.0.2 Operating Systems: AIX, Linux, Solaris, Windows

MapMessage

A map message is a message whose body comprises a set of name-value pairs, where each value has an associated data type.

When an application gets the value of name-value pair, the value can be converted by XMS into another data type. For more information about this form of implicit conversion, see Map messages.

Functions

Summary of functions:
Function Description
xmsMapMsgGetBoolean Get the boolean value identified by name from the body of the map message.
xmsMapMsgGetByte Get the byte identified by name from the body of the map message.
xmsMapMsgGetBytes Get the array of bytes identified by name from the body of the map message.
xmsMapMsgGetBytesByRef Get a pointer to an array of bytes in the body of the map message and get the length of the array.
xmsMapMsgGetChar Get the character identified by name from the body of the map message.
xmsMapMsgGetDouble Get the double precision floating point number identified by name from the body of the map message.
xmsMapMsgGetFloat Get the floating point number identified by name from the body of the map message.
xmsMapMsgGetInt Get the integer identified by name from the body of the map message.
xmsMapMsgGetLong Get the long integer identified by name from the body of the map message.
xmsMapMsgGetMap Get a list of the name-value pairs in the body of the map message.
xmsMapMsgGetObject Get the value of a name-value pair, and its data type, from the body of the map message.
xmsMapMsgGetShort Get the short integer identified by name from the body of the map message.
xmsMapMsgGetString Get the string identified by name from the body of the map message.
xmsMapMsgGetStringByRef Get a pointer to the string identified by name and get the length of the string.
xmsMapMsgItemExists Check whether the body of the map message contains a name-value pair with the specified name.
xmsMapMsgSetBoolean Set a boolean value in the body of the map message.
xmsMapMsgSetByte Set a byte in the body of the map message.
xmsMapMsgSetBytes Set an array of bytes in the body of the map message.
xmsMapMsgSetChar Set a 2-byte character in the body of the map message.
xmsMapMsgSetDouble Set a double precision floating point number in the body of the map message.
xmsMapMsgSetFloat Set a floating point number in the body of the map message.
xmsMapMsgSetInt Set an integer in the body of the map message.
xmsMapMsgSetLong Set a long integer in the body of the map message.
xmsMapMsgSetObject Set a value, with a specified data type, in the body of the map message.
xmsMapMsgSetShort Set a short integer in the body of the map message.
xmsMapMsgSetString Set a string in the body of the map message.

xmsMapMsgGetBoolean – Get Boolean Value

Interface:
xmsRC xmsMapMsgGetBoolean(xmsHMsg message,
                          xmsCHAR *name,
                          xmsBOOL *value,
                          xmsHErrorBlock errorBlock);

Get the boolean value identified by name from the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the boolean value. The name is in the format of a null terminated string.
value (output)
The boolean value retrieved from the body of the map message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetByte – Get Byte

Interface:
xmsRC xmsMapMsgGetByte(xmsHMsg message,
                       xmsCHAR *name,
                       xmsSBYTE *value,
                       xmsHErrorBlock errorBlock);

Get the byte identified by name from the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the byte. The name is in the format of a null terminated string.
value (output)
The byte retrieved from the body of the map message. No data conversion is performed on the byte.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetBytes – Get Bytes

Interface:
xmsRC xmsMapMsgGetBytes(xmsHMsg message,
                        xmsCHAR *name,
                        xmsSBYTE *buffer,
                        xmsINT bufferLength,
                        xmsINT *actualLength,
                        xmsHErrorBlock errorBlock);

Get the array of bytes identified by name from the body of the map message.

For more information about how to use this function, see C functions that return a byte array by value.

Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the array of bytes. The name is in the format of a null terminated string.
buffer (output)
The buffer to contain the array of bytes. No data conversion is performed on the bytes that are returned.
bufferLength (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE instead, the array of bytes is not returned, but its length is returned in the actualLength parameter.
actualLength (output)
The number of bytes in the array. If you specify a null pointer on input, the length of the array is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetBytesByRef – Get Bytes by Reference

Interface:
xmsRC xmsMapMsgGetBytesByRef(xmsHMsg message,
                             xmsCHAR *name,
                             xmsSBYTE **array,
                             xmsINT *length,
                             xmsHErrorBlock errorBlock);

Get a pointer to an array of bytes in the body of the map message and get the length of the array. The array of bytes is identified by name.

For more information about how to use this function, see C functions that return a string or byte array by reference.

Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the array of bytes. The name is in the format of a null terminated string.
array (output)
A pointer to the array of bytes.
length (output)
The number of bytes in the array.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetChar – Get Character

Interface:
xmsRC xmsMapMsgGetChar(xmsHMsg message,
                       xmsCHAR *name,
                       xmsCHAR16 *value,
                       xmsHErrorBlock errorBlock);

Get the character identified by name from the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the character. The name is in the format of a null terminated string.
value (output)
The character retrieved from the body of the map message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetDouble – Get Double Precision Floating Point Number

Interface:
xmsRC xmsMapMsgGetDouble(xmsHMsg message,
                         xmsCHAR *name,
                         xmsDOUBLE *value,
                         xmsHErrorBlock errorBlock);

Get the double precision floating point number identified by name from the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the double precision floating point number. The name is in the format of a null terminated string.
value (output)
The double precision floating point number retrieved from the body of the map message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetFloat – Get Floating Point Number

Interface:
xmsRC xmsMapMsgGetFloat(xmsHMsg message,
                        xmsCHAR *name,
                        xmsFLOAT *value,
                        xmsHErrorBlock errorBlock);

Get the floating point number identified by name from the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the floating point number. The name is in the format of a null terminated string.
value (output)
The floating point number retrieved from the body of the map message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetInt – Get Integer

Interface:
xmsRC xmsMapMsgGetInt(xmsHMsg message,
                      xmsCHAR *name,
                      xmsINT *value,
                      xmsHErrorBlock errorBlock);

Get the integer identified by name from the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the integer. The name is in the format of a null terminated string.
value (output)
The integer retrieved from the body of the map message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetLong – Get Long Integer

Interface:
xmsRC xmsMapMsgGetLong(xmsHMsg message,
                       xmsCHAR *name,
                       xmsLONG *value,
                       xmsHErrorBlock errorBlock);

Get the long integer identified by name from the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the long integer. The name is in the format of a null terminated string.
value (output)
The long integer retrieved from the body of the map message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetMap – Get Name-Value Pairs

Interface:
xmsRC xmsMapMsgGetMap(xmsHMsg message,
                      xmsHIterator *iterator,
                      xmsHErrorBlock errorBlock);

Get a list of the name-value pairs in the body of the map message.

The function returns an iterator that encapsulates a list of Property objects, where each Property object encapsulates a name-value pair. The application can then use the iterator to access each name-value pair in turn.

Note: The equivalent JMS method performs a slightly different function. The JMS method returns an enumeration of only the names, not the values, in the body of the map message.
Parameters:
message (input)
The handle for the message.
iterator (output)
The handle for the iterator.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetObject – Get Object

Interface:
xmsRC xmsMapMsgGetObject(xmsHMsg message,
                         xmsCHAR *name,
                         xmsSBYTE *buffer,
                         xmsINT bufferLength,
                         xmsINT *actualLength,
                         xmsOBJECT_TYPE *objectType,
                         xmsHErrorBlock errorBlock);

Get the value of a name-value pair, and its data type, from the body of the map message. The name-value pair is identified by name.

For more information about how to use this function, see C functions that return a byte array by value.

Parameters:
message (input)
The handle for the message.
name (input)
The name of the name-value pair in the format of a null terminated string.
buffer (output)
The buffer to contain the value, which is returned as an array of bytes. If the value is a string and data conversion is required, this is the value after conversion.
bufferLength (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE instead, the value is not returned, but its length is returned in the actualLength parameter.
actualLength (output)
The length of the value in bytes. If the value is a string and data conversion is required, this is the length after conversion. If you specify a null pointer on input, the length is not returned.
objectType (output)
The data type of the value, which is one of the following object types:
  • XMS_OBJECT_TYPE_BOOL
  • XMS_OBJECT_TYPE_BYTE
  • XMS_OBJECT_TYPE_BYTEARRAY
  • XMS_OBJECT_TYPE_CHAR
  • XMS_OBJECT_TYPE_DOUBLE
  • XMS_OBJECT_TYPE_FLOAT
  • XMS_OBJECT_TYPE_INT
  • XMS_OBJECT_TYPE_LONG
  • XMS_OBJECT_TYPE_SHORT
  • XMS_OBJECT_TYPE_STRING
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetShort – Get Short Integer

Interface:
xmsRC xmsMapMsgGetShort(xmsHMsg message,
                        xmsCHAR *name,
                        xmsSHORT *value,
                        xmsHErrorBlock errorBlock);

Get the short integer identified by name from the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the short integer. The name is in the format of a null terminated string.
value (output)
The short integer retrieved from the body of the map message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetString – Get String

Interface:
xmsRC xmsMapMsgGetString(xmsHMsg message,
                         xmsCHAR *name,
                         xmsCHAR *buffer,
                         xmsINT bufferLength,
                         xmsINT *actualLength,
                         xmsHErrorBlock errorBlock);

Get the string identified by name from the body of the map message.

For more information about how to use this function, see C functions that return a string by value.

Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the string. The name is in the format of a null terminated string.
buffer (output)
The buffer to contain the string. If data conversion is required, this is the string after conversion.
bufferLength (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE instead, the string is not returned, but its length is returned in the actualLength parameter.
actualLength (output)
The length of the string in bytes. If data conversion is required, this is the length of the string after conversion. If you specify a null pointer on input, the length is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetStringByRef – Get String by Reference

Interface:
xmsRC xmsMapMsgGetStringByRef(xmsHMsg message,
                              xmsCHAR *name,
                              xmsCHAR **string,
                              xmsINT *length,
                              xmsHErrorBlock errorBlock);

Get a pointer to the string identified by name and get the length of the string.

For more information about how to use this function, see C functions that return a string or byte array by reference.

Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the string. The name is in the format of a null terminated string.
string (output)
A pointer to the string. If data conversion is required, this is the string after conversion.
length (output)
The length of the string in bytes. If data conversion is required, this is the length after conversion.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgItemExists – Check Name-Value Pair Exists

Interface:
xmsRC xmsMapMsgItemExists(xmsHMsg message,
                          xmsCHAR *name,
                          xmsBOOL *pairExists,
                          xmsHErrorBlock errorBlock);

Check whether the body of the map message contains a name-value pair with the specified name.

Parameters:
message (input)
The handle for the message.
name (input)
The name of the name-value pair in the format of a null terminated string.
pairExists (output)
The value is xmsTRUE if the body of the map message contains a name-value pair with the specified name. The value is xmsFALSE if the body of the map message does not contain a name-value pair with the specified name.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgSetBoolean – Set Boolean Value

Interface:
xmsRC xmsMapMsgSetBoolean(xmsHMsg message,
                          xmsCHAR *name,
                          xmsBOOL value,
                          xmsHErrorBlock errorBlock);

Set a boolean value in the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name to identify the boolean value in the body of the map message. The name is in the format of a null terminated string.
value (input)
The boolean value to be set.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgSetByte – Set Byte

Interface:
xmsRC xmsMapMsgSetByte(xmsHMsg message,
                       xmsCHAR *name,
                       xmsSBYTE value,
                       xmsHErrorBlock errorBlock);

Set a byte in the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name to identify the byte in the body of the map message. The name is in the format of a null terminated string.
value (input)
The byte to be set.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgSetBytes – Set Bytes

Interface:
xmsRC xmsMapMsgSetBytes(xmsHMsg message,
                        xmsCHAR *name,
                        xmsSBYTE *value,
                        xmsINT length,
                        xmsHErrorBlock errorBlock);

Set an array of bytes in the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name to identify the array of bytes in the body of the map message. The name is in the format of a null terminated string.
value (input)
The array of bytes to be set.
length (input)
The number of bytes in the array.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgSetChar – Set Character

Interface:
xmsRC xmsMapMsgSetChar(xmsHMsg message,
                       xmsCHAR *name,
                       xmsCHAR16 value,
                       xmsHErrorBlock errorBlock);

Set a 2-byte character in the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name to identify the character in the body of the map message. The name is in the format of a null terminated string.
value (input)
The character to be set.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgSetDouble – Set Double Precision Floating Point Number

Interface:
xmsRC xmsMapMsgSetDouble(xmsHMsg message,
                         xmsCHAR *name,
                         xmsDOUBLE value,
                         xmsHErrorBlock errorBlock);

Set a double precision floating point number in the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name to identify the double precision floating point number in the body of the map message. The name is in the format of a null terminated string.
value (input)
The double precision floating point number to be set.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgSetFloat – Set Floating Point Number

Interface:
xmsRC xmsMapMsgSetFloat(xmsHMsg message,
                        xmsCHAR *name,
                        xmsFLOAT value,
                        xmsHErrorBlock errorBlock);

Set a floating point number in the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name to identify the floating point number in the body of the map message. The name is in the format of a null terminated string.
value (input)
The floating point number to be set.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgSetInt – Set Integer

Interface:
xmsRC xmsMapMsgSetInt(xmsHMsg message,
                      xmsCHAR *name,
                      xmsINT value,
                      xmsHErrorBlock errorBlock);

Set an integer in the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name to identify the integer in the body of the map message. The name is in the format of a null terminated string.
value (input)
The integer to be set.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgSetLong – Set Long Integer

Interface:
xmsRC xmsMapMsgSetLong(xmsHMsg message,
                       xmsCHAR *name,
                       xmsLONG value,
                       xmsHErrorBlock errorBlock);

Set a long integer in the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name to identify the long integer in the body of the map message. The name is in the format of a null terminated string.
value (input)
The long integer to be set.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgSetObject – Set Object

Interface:
xmsRC xmsMapMsgSetObject(xmsHMsg message,
                         xmsCHAR *name,
                         xmsSBYTE *value,
                         xmsINT length,
                         xmsOBJECT_TYPE objectType,
                         xmsHErrorBlock errorBlock);

Set a value, with a specified data type, in the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name to identify the value in the body of the map message. The name is in the format of a null terminated string.
value (input)
An array of bytes containing the value to be set.
length (input)
The number of bytes in the array.
objectType (input)
The data type of the value, which must be one of the following object types:
  • XMS_OBJECT_TYPE_BOOL
  • XMS_OBJECT_TYPE_BYTE
  • XMS_OBJECT_TYPE_BYTEARRAY
  • XMS_OBJECT_TYPE_CHAR
  • XMS_OBJECT_TYPE_DOUBLE
  • XMS_OBJECT_TYPE_FLOAT
  • XMS_OBJECT_TYPE_INT
  • XMS_OBJECT_TYPE_LONG
  • XMS_OBJECT_TYPE_SHORT
  • XMS_OBJECT_TYPE_STRING
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgSetShort – Set Short Integer

Interface:
xmsRC xmsMapMsgSetShort(xmsHMsg message,
                        xmsCHAR *name,
                        xmsSHORT value,
                        xmsHErrorBlock errorBlock);

Set a short integer in the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name to identify the short integer in the body of the map message. The name is in the format of a null terminated string.
value (input)
The short integer to be set.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsMapMsgSetString – Set String

Interface:
xmsRC xmsMapMsgSetString(xmsHMsg message,
                         xmsCHAR *name,
                         xmsCHAR *value,
                         xmsINT length,
                         xmsHErrorBlock errorBlock);

Set a string in the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name to identify the string in the body of the map message. The name is in the format of a null terminated string.
value (input)
A character array containing the string to be set.
length (input)
The length of the string in bytes. If the string is null terminated with no embedded null characters, you can specify XMSC_CALCULATE_STRING_SIZE instead and allow XMS to calculate its length.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

Reference topic

Terms of Use | Rate this page

Last updated: 24 May 2011

(C) Copyright IBM Corporation 2005, 2011. All Rights Reserved.