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

BytesMessage

A bytes message is a message whose body comprises a stream of bytes.

Inheritance hierarchy:
xms::PropertyContext
   |
   +----xms::Message
           |
           +----xms::BytesMessage
Related reference
Bytes messages

Methods

Summary of methods:
Method Description
getBodyLength Get the length of the body of the message when the body of the message is read-only.
readBoolean Read a boolean value from the bytes message stream.
readByte Read the next byte from the bytes message stream as a signed 8-bit integer.
readBytes Read an array of bytes from the bytes message stream starting from the current position of the cursor.
readChar Read the next 2 bytes from the bytes message stream as a character.
readDouble Read the next 8 bytes from the bytes message stream as a double precision floating point number.
readFloat Read the next 4 bytes from the bytes message stream as a floating point number.
readInt Read the next 4 bytes from the bytes message stream as a signed 32-bit integer.
readLong Read the next 8 bytes from the bytes message stream as a signed 64-bit integer.
readShort Read the next 2 bytes from the bytes message stream as a signed 16-bit integer.
readUnsignedByte Read the next byte from the bytes message stream as an unsigned 8-bit integer.
readUnsignedShort Read the next 2 bytes from the bytes message stream as an unsigned 16-bit integer.
readUTF Read a string, encoded in UTF-8, from the bytes message stream.
reset Put the body of the message into read-only mode and reposition the cursor at the beginning of the bytes message stream.
writeBoolean Write a boolean value to the bytes message stream.
writeByte Write a byte to the bytes message stream.
writeBytes Write an array of bytes to the bytes message stream.
writeChar Write a character to the bytes 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 bytes message stream as 8 bytes, high order byte first.
writeFloat Convert a floating point number to an integer and write the integer to the bytes message stream as 4 bytes, high order byte first.
writeInt Write an integer to the bytes message stream as 4 bytes, high order byte first.
writeLong Write a long integer to the bytes message stream as 8 bytes, high order byte first.
writeShort Write a short integer to the bytes message stream as 2 bytes, high order byte first.
writeUTF Write a string, encoded in UTF-8, to the bytes message stream.

getBodyLength – Get Body Length

Interface:
xmsLONG getBodyLength() const;

Get the length of the body of the message when the body of the message is read-only.

Parameters:
None
Returns:
The length of the body of the message in bytes. The method returns the length of the whole body regardless of where the cursor for reading the message is currently positioned.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION

readBoolean – Read Boolean Value

Interface:
xmsBOOL readBoolean() const;

Read a boolean value from the bytes 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 the next byte from the bytes message stream as a signed 8-bit integer.

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 bytes message stream starting from the current position of the cursor.

Parameters:
buffer (output)
The buffer to contain the array of bytes that is read. If the number of bytes remaining to be read from the stream before the call is greater than or equal to the length of the buffer, the buffer is filled. Otherwise, the buffer is partially filled with all the remaining bytes.

If you specify a null pointer on input, the method skips over the bytes without reading them. If the number of bytes remaining to be read from the stream before the call is greater than or equal to the length of the buffer, the number of bytes skipped is equal to the length of the buffer. Otherwise, all the remaining bytes are skipped.

bufferLength (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE instead, no bytes are read into the buffer, but the number of bytes remaining in the stream, starting from the current position of the cursor, is returned in the returnedLength parameter, and the cursor is not advanced.
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 remaining to be read. If there are no bytes remaining to be read from the stream before the call, the value is XMSC_END_OF_STREAM.

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

readChar – Read Character

Interface:
xmsCHAR16 readChar() const;

Read the next 2 bytes from the bytes message stream as a character.

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 the next 8 bytes from the bytes message stream as a double precision floating point number.

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 the next 4 bytes from the bytes message stream as a floating point number.

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 the next 4 bytes from the bytes message stream as a signed 32-bit integer.

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 the next 8 bytes from the bytes message stream as a signed 64-bit integer.

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

readShort – Read Short Integer

Interface:
xmsSHORT readShort() const;

Read the next 2 bytes from the bytes message stream as a signed 16-bit integer.

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

readUnsignedByte – Read Unsigned Byte

Interface:
xmsBYTE readUnsignedByte() const;

Read the next byte from the bytes message stream as an unsigned 8-bit integer.

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

readUnsignedShort – Read Unsigned Short Integer

Interface:
xmsUSHORT readUnsignedShort() const;

Read the next 2 bytes from the bytes message stream as an unsigned 16-bit integer.

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

readUTF – Read UTF String

Interface:
String readUTF() const;

Read a string, encoded in UTF-8, from the bytes message stream. If required, XMS converts the characters in the string from UTF-8 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 bytes message stream.

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

writeBoolean – Write Boolean Value

Interface:
xmsVOID writeBoolean(const xmsBOOL value);

Write a boolean value to the bytes 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 bytes 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 bytes 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 bytes 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 bytes 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 bytes 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 bytes 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 bytes 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

writeShort – Write Short Integer

Interface:
xmsVOID writeShort(const xmsSHORT value);

Write a short integer to the bytes 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

writeUTF – Write UTF String

Interface:
xmsVOID writeUTF(const String & value);

Write a string, encoded in UTF-8, to the bytes message stream. If required, XMS converts the characters in the string from the local code page into UTF-8.

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: 18 Jun 2008

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