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

StreamMessage

A stream message is a message whose body comprises a stream of values, where each value has an associated data type.

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

The contents of the body are written and read sequentially.

When an application reads a value from the message stream, the value can be converted by XMS into another data type. For more information about this form of implicit conversion, see Stream messages.

Methods

Summary of methods:
Method Description
readBoolean Read a boolean value from the message stream.
readByte Read a signed 8-bit integer from the message stream.
readBytes Read an array of bytes from the message stream.
readChar Read a 2-byte character from the message stream.
readDouble Read an 8-byte double precision floating point number from the message stream.
readFloat Read a 4-byte floating point number from the message stream.
readInt Read a signed 32-bit integer from the message stream.
readLong Read a signed 64-bit integer from the message stream.
readObject Read a value from the message stream, and return its data type.
readShort Read a signed 16-bit integer from the message stream.
readString Read a string from the message stream.
reset Put the body of the message into read-only mode and reposition the cursor at the beginning of the message stream.
writeBoolean Write a boolean value to the message stream.
writeByte Write a byte to the message stream.
writeBytes Write an array of bytes to the message stream.
writeChar Write a character to the message stream as 2 bytes, high order byte first.
writeDouble Convert a double precision floating point number to a long integer and write the long integer to the message stream as 8 bytes, high order byte first.
writeFloat Convert a floating point number to an integer and write the integer to the message stream as 4 bytes, high order byte first.
writeInt Write an integer to the message stream as 4 bytes, high order byte first.
writeLong Write a long integer to the message stream as 8 bytes, high order byte first.
writeObject Write a value, with a specified data type, to the message stream.
writeShort Write a short integer to the message stream as 2 bytes, high order byte first.
writeString Write a string to the message stream.

readBoolean – Read Boolean Value

Interface:
xmsBOOL readBoolean() const;

Read a boolean value from the message stream.

Parameters:
None
Returns:
The boolean value that is read.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

readByte – Read Byte

Interface:
xmsSBYTE readByte() const;

Read a signed 8-bit integer from the message stream.

Parameters:
None
Returns:
The byte that is read.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

readBytes – Read Bytes

Interface:
xmsINT readBytes(xmsSBYTE *buffer,
                 const xmsINT bufferLength,
                 xmsINT *returnedLength) const;

Read an array of bytes from the message stream.

Parameters:
buffer (output)
The buffer to contain the array of bytes that is read.

If the number of bytes in the array is less than or equal to the length of the buffer, the whole array is read into the buffer. If the number of bytes in the array is greater than the length of the buffer, the buffer is filled with part of the array, and an internal cursor marks the position of the next byte to be read. A subsequent call to readBytes() reads bytes from the array starting from the current position of the cursor.

If you specify a null pointer on input, the call skips over the array of bytes without reading it.

bufferLength (input)
The length of the buffer in bytes.
returnedLength (output)
The number of bytes that are read into the buffer. If the buffer is partially filled, the value is less than the length of the buffer, indicating that there are no more bytes in the array remaining to be read. If there are no bytes remaining to be read from the array before the call, the value is XMSC_END_OF_BYTEARRAY.

If you specify a null pointer on input, the method returns no value.

Returns:
See the description of the returnedLength parameter.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

readChar – Read Character

Interface:
xmsCHAR16 readChar() const;

Read a 2-byte character from the message stream.

Parameters:
None
Returns:
The character that is read.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

readDouble – Read Double Precision Floating Point Number

Interface:
xmsDOUBLE readDouble() const;

Read an 8-byte double precision floating point number from the message stream.

Parameters:
None
Returns:
The double precision floating point number that is read.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

readFloat – Read Floating Point Number

Interface:
xmsFLOAT readFloat() const;

Read a 4-byte floating point number from the message stream.

Parameters:
None
Returns:
The floating point number that is read.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

readInt – Read Integer

Interface:
xmsINT readInt() const;

Read a signed 32-bit integer from the message stream.

Parameters:
None
Returns:
The integer that is read.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

readLong – Read Long Integer

Interface:
xmsLONG readLong() const;

Read a signed 64-bit integer from the message stream.

Parameters:
None
Returns:
The long integer that is read.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

readObject – Read Object

Interface:
xmsOBJECT_TYPE readObject(xmsSBYTE *buffer,
                          const xmsINT bufferLength,
                          xmsINT *actualLength) const;

Read a value from the message stream, and return its data type.

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

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

If you specify a null pointer on input, the call skips over the value without reading it.

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

readShort – Read Short Integer

Interface:
xmsSHORT readShort() const;

Read a signed 16-bit integer from the message stream.

Parameters:
None
Returns:
The short integer that is read.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

readString – Read String

Interface:
String readString() const;

Read a string from the message stream. If required, XMS converts the characters in the string into the local code page.

Parameters:
None
Returns:
A String object encapsulating the string that is read. If data conversion is required, this is the string after conversion.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

reset – Reset

Interface:
xmsVOID reset() const;

Put the body of the message into read-only mode and reposition the cursor at the beginning of the message stream.

Parameters:
None
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

writeBoolean – Write Boolean Value

Interface:
xmsVOID writeBoolean(const xmsBOOL value);

Write a boolean value to the message stream.

Parameters:
value (input)
The boolean value to be written.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

writeByte – Write Byte

Interface:
xmsVOID writeByte(const xmsSBYTE value);

Write a byte to the message stream.

Parameters:
value (input)
The byte to be written.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

writeBytes – Write Bytes

Interface:
xmsVOID writeBytes(const xmsSBYTE *value,
                   const xmsINT length);

Write an array of bytes to the message stream.

Parameters:
value (input)
The array of bytes to be written.
length (input)
The number of bytes in the array.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

writeChar – Write Character

Interface:
xmsVOID writeChar(const xmsCHAR16 value);

Write a character to the message stream as 2 bytes, high order byte first.

Parameters:
value (input)
The character to be written.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

writeDouble – Write Double Precision Floating Point Number

Interface:
xmsVOID writeDouble(const xmsDOUBLE value);

Convert a double precision floating point number to a long integer and write the long integer to the message stream as 8 bytes, high order byte first.

Parameters:
value (input)
The double precision floating point number to be written.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

writeFloat – Write Floating Point Number

Interface:
xmsVOID writeFloat(const xmsFLOAT value);

Convert a floating point number to an integer and write the integer to the message stream as 4 bytes, high order byte first.

Parameters:
value (input)
The floating point number to be written.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

writeInt – Write Integer

Interface:
xmsVOID writeInt(const xmsINT value);

Write an integer to the message stream as 4 bytes, high order byte first.

Parameters:
value (input)
The integer to be written.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

writeLong – Write Long Integer

Interface:
xmsVOID writeLong(const xmsLONG value);

Write a long integer to the message stream as 8 bytes, high order byte first.

Parameters:
value (input)
The long integer to be written.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

writeObject – Write Object

Interface:
xmsVOID writeObject(const xmsOBJECT_TYPE objectType,
                    const xmsSBYTE *value,
                    const xmsINT length);

Write a value, with a specified data type, to the message stream.

Parameters:
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 written.
length (input)
The number of bytes in the array.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

writeShort – Write Short Integer

Interface:
xmsVOID writeShort(const xmsSHORT value);

Write a short integer to the message stream as 2 bytes, high order byte first.

Parameters:
value (input)
The short integer to be written.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

writeString – Write String

Interface:
xmsVOID writeString(const String & value);

Write a string to the message stream.

Parameters:
value (input)
A String object encapsulating the string to be written.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

Inherited methods


Reference topic

Terms of Use | Rate this page

Last updated: 24 May 2011

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