WebSphere WebSphere Business Integration Message Service Clients for C/C++ Version 1.2.7 and .NET Version 1.2.6 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.

Inheritance hierarchy:
xms::PropertyContext
   |
   +----xms::Message
           |
           +----xms::MapMessage

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.

Related reference
Map messages

Methods

Summary of methods:
Method Description
getBoolean Get the boolean value identified by name from the body of the map message.
getByte Get the byte identified by name from the body of the map message.
getBytes Get the array of bytes identified by name from the body of the map message.
getChar Get the character identified by name from the body of the map message.
getDouble Get the double precision floating point number identified by name from the body of the map message.
getFloat Get the floating point number identified by name from the body of the map message.
getInt Get the integer identified by name from the body of the map message.
getLong Get the long integer identified by name from the body of the map message.
getMap Get a list of the name-value pairs in the body of the map message.
getObject Get the value of a name-value pair, and its data type, from the body of the map message.
getShort Get the short integer identified by name from the body of the map message.
getString Get the string identified by name from the body of the map message.
itemExists Check whether the body of the map message contains a name-value pair with the specified name.
setBoolean Set a boolean value in the body of the map message.
setByte Set a byte in the body of the map message.
setBytes Set an array of bytes in the body of the map message.
setChar Set a 2-byte character in the body of the map message.
setDouble Set a double precision floating point number in the body of the map message.
setFloat Set a floating point number in the body of the map message.
setInt Set an integer in the body of the map message.
setLong Set a long integer in the body of the map message.
setObject Set a value, with a specified data type, in the body of the map message.
setShort Set a short integer in the body of the map message.
setString Set a string in the body of the map message.

getBoolean – Get Boolean Value

Interface:
xmsBOOL getBoolean(const String & name) const;

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

Parameters:
name (input)
A String object encapsulating the name that identifies the boolean value.
Returns:
The boolean value retrieved from the body of the map message.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getByte – Get Byte

Interface:
xmsSBYTE getByte(const String & name) const;

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

Parameters:
name (input)
A String object encapsulating the name that identifies the byte.
Returns:
The byte retrieved from the body of the map message. No data conversion is performed on the byte.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getBytes – Get Bytes

Interface:
xmsINT getBytes(const String & name,
                xmsSBYTE *buffer,
                const xmsINT bufferLength,
                xmsINT *actualLength) const;

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

For more information about how to use this method, see C++ methods that return a byte array.

Parameters:
name (input)
A String object encapsulating the name that identifies the array of bytes.
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.
Returns:
The number of bytes in the array.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getChar – Get Character

Interface:
xmsCHAR16 getChar(const String & name) const;

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

Parameters:
name (input)
A String object encapsulating the name that identifies the character.
Returns:
The character retrieved from the body of the map message.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getDouble – Get Double Precision Floating Point Number

Interface:
xmsDOUBLE getDouble(const String & name) const;

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

Parameters:
name (input)
A String object encapsulating the name that identifies the double precision floating point number.
Returns:
The double precision floating point number retrieved from the body of the map message.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getFloat – Get Floating Point Number

Interface:
xmsFLOAT getFloat(const String & name) const;

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

Parameters:
name (input)
A String object encapsulating the name that identifies the floating point number.
Returns:
The floating point number retrieved from the body of the map message.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getInt – Get Integer

Interface:
xmsINT getInt(const String & name) const;

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

Parameters:
name (input)
A String object encapsulating the name that identifies the integer.
Returns:
The integer retrieved from the body of the map message.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getLong – Get Long Integer

Interface:
xmsLONG getLong(const String & name) const;

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

Parameters:
name (input)
A String object encapsulating the name that identifies the long integer.
Returns:
The long integer retrieved from the body of the map message.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getMap – Get Name-Value Pairs

Interface:
Iterator getMap() const;

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

The method 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:
None
Returns:
The Iterator object.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getObject – Get Object

Interface:
xmsOBJECT_TYPE getObject(const String & name,
                         xmsSBYTE *buffer,
                         const xmsINT bufferLength,
                         xmsINT *actualLength) const;

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 method, see C++ methods that return a byte array.

Parameters:
name (input)
A String object encapsulating the name of the name-value pair.
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.
Returns:
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
Exceptions:
XMS_X_GENERAL_EXCEPTION

getShort – Get Short Integer

Interface:
xmsSHORT getShort(const String & name) const;

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

Parameters:
name (input)
A String object encapsulating the name that identifies the short integer.
Returns:
The short integer retrieved from the body of the map message.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getString – Get String

Interface:
String getString(const String & name) const;

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

Parameters:
name (input)
A String object encapsulating the name that identifies the string in the body of the map message.
Returns:
A String object encapsulating the string retrieved from the body of the map message. If data conversion is required, this is the string after conversion.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

itemExists – Check Name-Value Pair Exists

Interface:
xmsBOOL itemExists(const String & name) const;

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

Parameters:
name (input)
A String object encapsulating the name of the name-value pair.
Returns:
  • xmsTRUE, if the body of the map message contains a name-value pair with the specified name.
  • xmsFALSE, if the body of the map message does not contain a name-value pair with the specified name.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

setBoolean – Set Boolean Value

Interface:
xmsVOID setBoolean(const String & name,
                   const xmsBOOL value);

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

Parameters:
name (input)
A String object encapsulating the name to identify the boolean value in the body of the map message.
value (input)
The boolean value to be set.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

setByte – Set Byte

Interface:
xmsVOID setByte(const String & name,
                const xmsSBYTE value);

Set a byte in the body of the map message.

Parameters:
name (input)
A String object encapsulating the name to identify the byte in the body of the map message.
value (input)
The byte to be set.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

setBytes – Set Bytes

Interface:
xmsVOID setBytes(const String & name,
                 const xmsSBYTE *value,
                 const xmsINT length);

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

Parameters:
name (input)
A String object encapsulating the name to identify the array of bytes in the body of the map message.
value (input)
The array of bytes to be set.
length (input)
The number of bytes in the array.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

setChar – Set Character

Interface:
xmsVOID setChar(const String & name,
                const xmsCHAR16 value);

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

Parameters:
name (input)
A String object encapsulating the name to identify the character in the body of the map message.
value (input)
The character to be set.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

setDouble – Set Double Precision Floating Point Number

Interface:
xmsVOID setDouble(const String & name,
                  const xmsDOUBLE value);

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

Parameters:
name (input)
A String object encapsulating the name to identify the double precision floating point number in the body of the map message.
value (input)
The double precision floating point number to be set.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

setFloat – Set Floating Point Number

Interface:
xmsVOID setFloat(const String & name,
                 const xmsFLOAT value);

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

Parameters:
name (input)
A String object encapsulating the name to identify the floating point number in the body of the map message.
value (input)
The floating point number to be set.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

setInt – Set Integer

Interface:
xmsVOID setInt(const String & name,
               const xmsINT value);

Set an integer in the body of the map message.

Parameters:
name (input)
A String object encapsulating the name to identify the integer in the body of the map message.
value (input)
The integer to be set.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

setLong – Set Long Integer

Interface:
xmsVOID setLong(const String & name,
                const xmsLONG value);

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

Parameters:
name (input)
A String object encapsulating the name to identify the long integer in the body of the map message.
value (input)
The long integer to be set.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

setObject – Set Object

Interface:
xmsVOID setObject(const String & name,
                  const xmsOBJECT_TYPE objectType,
                  const xmsSBYTE *value,
                  const xmsINT length);

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

Parameters:
name (input)
A String object encapsulating the name to identify the value in the body of the map message.
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
value (input)
An array of bytes containing the value to be set.
length (input)
The number of bytes in the array.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

setShort – Set Short Integer

Interface:
xmsVOID setShort(const String & name,
                 const xmsSHORT value);

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

Parameters:
name (input)
A String object encapsulating the name to identify the short integer in the body of the map message.
value (input)
The short integer to be set.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

setString – Set String

Interface:
xmsVOID setString(const String & name,
                  const String value);

Set a string in the body of the map message.

Parameters:
name (input)
A String object encapsulating the name to identify the string in the body of the map message.
value (input)
A String object encapsulating the string to be set.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

Inherited methods


Reference topic

Terms of Use | Rate this page

Last updated: 18 Jun 2008

© Copyright IBM Corporation 2005, 2008. All Rights Reserved.