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

BytesMessage

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

Functions

Summary of functions:
Function Description
xmsBytesMsgGetBodyLength Get the length of the body of the message when the body of the message is read-only.
xmsBytesMsgReadBoolean Read a boolean value from the bytes message stream.
xmsBytesMsgReadByte Read the next byte from the bytes message stream as a signed 8-bit integer.
xmsBytesMsgReadBytes Read an array of bytes from the bytes message stream starting from the current position of the cursor.
xmsBytesMsgReadBytesByRef Get a pointer to the start of the bytes message stream and get the length of the stream.
xmsBytesMsgReadChar Read the next 2 bytes from the bytes message stream as a character.
xmsBytesMsgReadDouble Read the next 8 bytes from the bytes message stream as a double precision floating point number.
xmsBytesMsgReadFloat Read the next 4 bytes from the bytes message stream as a floating point number.
xmsBytesMsgReadInt Read the next 4 bytes from the bytes message stream as a signed 32-bit integer.
xmsBytesMsgReadLong Read the next 8 bytes from the bytes message stream as a signed 64-bit integer.
xmsBytesMsgReadShort Read the next 2 bytes from the bytes message stream as a signed 16-bit integer.
xmsBytesMsgReadUnsignedByte Read the next byte from the bytes message stream as an unsigned 8-bit integer.
xmsBytesMsgReadUnsignedShort Read the next 2 bytes from the bytes message stream as an unsigned 16-bit integer.
xmsBytesMsgReadUTF Read a string, encoded in UTF-8, from the bytes message stream.
xmsBytesMsgReset Put the body of the message into read-only mode and reposition the cursor at the beginning of the bytes message stream.
xmsBytesMsgWriteBoolean Write a boolean value to the bytes message stream.
xmsBytesMsgWriteByte Write a byte to the bytes message stream.
xmsBytesMsgWriteBytes Write an array of bytes to the bytes message stream.
xmsBytesMsgWriteChar Write a character to the bytes message stream as 2 bytes, high order byte first.
xmsBytesMsgWriteDouble 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.
xmsBytesMsgWriteFloat Convert a floating point number to an integer and write the integer to the bytes message stream as 4 bytes, high order byte first.
xmsBytesMsgWriteInt Write an integer to the bytes message stream as 4 bytes, high order byte first.
xmsBytesMsgWriteLong Write a long integer to the bytes message stream as 8 bytes, high order byte first.
xmsBytesMsgWriteShort Write a short integer to the bytes message stream as 2 bytes, high order byte first.
xmsBytesMsgWriteUTF Write a string, encoded in UTF-8, to the bytes message stream.

xmsBytesMsgGetBodyLength – Get Body Length

Interface:
xmsRC xmsBytesMsgGetBodyLength(xmsHMsg message,
                               xmsLONG *bodyLength,
                               xmsHErrorBlock errorBlock);

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

Parameters:
message (input)
The handle for the message.
bodyLength (output)
The length of the body of the message in bytes. The function returns the length of the whole body regardless of where the cursor for reading the message is currently positioned.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION

xmsBytesMsgReadBoolean – Read Boolean Value

Interface:
xmsRC xmsBytesMsgReadBoolean(xmsHMsg message,
                             xmsBOOL *value,
                             xmsHErrorBlock errorBlock);

Read a boolean value from the bytes message stream.

Parameters:
message (input)
The handle for the message.
value (output)
The boolean value that is read. If you specify a null pointer on input, the function skips over the boolean value without reading it.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadByte – Read Byte

Interface:
xmsRC xmsBytesMsgReadByte(xmsHMsg message,
                          xmsSBYTE *value,
                          xmsHErrorBlock errorBlock);

Read the next byte from the bytes message stream as a signed 8-bit integer.

Parameters:
message (input)
The handle for the message.
value (output)
The byte that is read. If you specify a null pointer on input, the function skips over the byte without reading it.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadBytes – Read Bytes

Interface:
xmsRC xmsBytesMsgReadBytes(xmsHMsg message,
                           xmsSBYTE *buffer,
                           xmsINT bufferLength,
                           xmsINT *returnedLength,
                           xmsHErrorBlock errorBlock);

Read an array of bytes from the bytes message stream starting from the current position of the cursor.

Parameters:
message (input)
The handle for the message.
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 function 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 function returns no value.

errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION

xmsBytesMsgReadBytesByRef – Read Bytes by Reference

Interface:
xmsRC xmsBytesMsgReadBytesByRef(xmsHMsg message,
                                xmsSBYTE **stream,
                                xmsINT *length,
                                xmsHErrorBlock errorBlock);

Get a pointer to the start of the bytes message stream and get the length of the stream.

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.
stream (output)
A pointer to the start of the bytes message stream.
length (output)
The number of bytes in the bytes message stream.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION

xmsBytesMsgReadChar – Read Character

Interface:
xmsRC xmsBytesMsgReadChar(xmsHMsg message,
                          xmsCHAR16 *value,
                          xmsHErrorBlock errorBlock);

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

Parameters:
message (input)
The handle for the message.
value (output)
The character that is read. If you specify a null pointer on input, the function skips over the bytes without reading them.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadDouble – Read Double Precision Floating Point Number

Interface:
xmsRC xmsBytesMsgReadDouble(xmsHMsg message,
                            xmsDOUBLE *value,
                            xmsHErrorBlock errorBlock);

Read the next 8 bytes from the bytes message stream as a double precision floating point number.

Parameters:
message (input)
The handle for the message.
value (output)
The double precision floating point number that is read. If you specify a null pointer on input, the function skips over the bytes without reading them.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadFloat – Read Floating Point Number

Interface:
xmsRC xmsBytesMsgReadFloat(xmsHMsg message,
                           xmsFLOAT *value,
                           xmsHErrorBlock errorBlock);

Read the next 4 bytes from the bytes message stream as a floating point number.

Parameters:
message (input)
The handle for the message.
value (output)
The floating point number that is read. If you specify a null pointer on input, the function skips over the bytes without reading them.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadInt – Read Integer

Interface:
xmsRC xmsBytesMsgReadInt(xmsHMsg message,
                         xmsINT *value,
                         xmsHErrorBlock errorBlock);

Read the next 4 bytes from the bytes message stream as a signed 32-bit integer.

Parameters:
message (input)
The handle for the message.
value (output)
The integer that is read. If you specify a null pointer on input, the function skips over the bytes without reading them.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadLong – Read Long Integer

Interface:
xmsRC xmsBytesMsgReadLong(xmsHMsg message,
                          xmsLONG *value,
                          xmsHErrorBlock errorBlock);

Read the next 8 bytes from the bytes message stream as a signed 64-bit integer.

Parameters:
message (input)
The handle for the message.
value (output)
The long integer that is read. If you specify a null pointer on input, the function skips over the bytes without reading them.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadShort – Read Short Integer

Interface:
xmsRC xmsBytesMsgReadShort(xmsHMsg message,
                           xmsSHORT *value,
                           xmsHErrorBlock errorBlock);

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

Parameters:
message (input)
The handle for the message.
value (output)
The short integer that is read. If you specify a null pointer on input, the function skips over the bytes without reading them.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadUnsignedByte – Read Unsigned Byte

Interface:
xmsRC xmsBytesMsgReadUnsignedByte(xmsHMsg message,
                                  xmsBYTE *value,
                                  xmsHErrorBlock errorBlock);

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

Parameters:
message (input)
The handle for the message.
value (output)
The byte that is read. If you specify a null pointer on input, the function skips over the byte without reading it.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadUnsignedShort – Read Unsigned Short Integer

Interface:
xmsRC xmsBytesMsgReadUnsignedShort(xmsHMsg message,
                                   xmsUSHORT *value,
                                   xmsHErrorBlock errorBlock);

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

Parameters:
message (input)
The handle for the message.
value (output)
The unsigned short integer that is read. If you specify a null pointer on input, the function skips over the bytes without reading them.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadUTF – Read UTF String

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

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.

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.
buffer (output)
The buffer to contain the string that is read. 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, the string is not returned, but its length is returned in the actualLength parameter, and the cursor is not advanced.

If you specify XMSC_SKIP, the function skips over the string without reading it.

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
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION
Notes:
  1. If the buffer is not large enough to store the whole string, XMS returns the string truncated to the length of the buffer, sets the actualLength parameter to the actual length of the string, and returns an error. XMS does not advance the internal cursor.
  2. If any other error occurs while attempting to read the string, XMS reports the error but does not set the actualLength parameter or advance the internal cursor.

xmsBytesMsgReset – Reset

Interface:
xmsRC xmsBytesMsgReset(xmsHMsg message,
                       xmsHErrorBlock errorBlock);

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

Parameters:
message (input)
The handle for the message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION

xmsBytesMsgWriteBoolean – Write Boolean Value

Interface:
xmsRC xmsBytesMsgWriteBoolean(xmsHMsg message,
                              xmsBOOL value,
                              xmsHErrorBlock errorBlock);

Write a boolean value to the bytes message stream.

Parameters:
message (input)
The handle for the message.
value (input)
The boolean value to be written.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteByte – Write Byte

Interface:
xmsRC xmsBytesMsgWriteByte(xmsHMsg message,
                           xmsSBYTE value,
                           xmsHErrorBlock errorBlock);

Write a byte to the bytes message stream.

Parameters:
message (input)
The handle for the message.
value (input)
The byte to be written.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteBytes – Write Bytes

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

Write an array of bytes to the bytes message stream.

Parameters:
message (input)
The handle for the message.
value (input)
The array of bytes to be written.
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
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteChar – Write Character

Interface:
xmsRC xmsBytesMsgWriteChar(xmsHMsg message,
                           xmsCHAR16 value,
                           xmsHErrorBlock errorBlock);

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

Parameters:
message (input)
The handle for the message.
value (input)
The character to be written.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteDouble – Write Double Precision Floating Point Number

Interface:
xmsRC xmsBytesMsgWriteDouble(xmsHMsg message,
                             xmsDOUBLE value,
                             xmsHErrorBlock errorBlock);

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:
message (input)
The handle for the message.
value (input)
The double precision floating point number to be written.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteFloat – Write Floating Point Number

Interface:
xmsRC xmsBytesMsgWriteFloat(xmsHMsg message,
                            xmsFLOAT value,
                            xmsHErrorBlock errorBlock);

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:
message (input)
The handle for the message.
value (input)
The floating point number to be written.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteInt – Write Integer

Interface:
xmsRC xmsBytesMsgWriteInt(xmsHMsg message,
                          xmsINT value,
                          xmsHErrorBlock errorBlock);

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

Parameters:
message (input)
The handle for the message.
value (input)
The integer to be written.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteLong – Write Long Integer

Interface:
xmsRC xmsBytesMsgWriteLong(xmsHMsg message,
                           xmsLONG value,
                           xmsHErrorBlock errorBlock);

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

Parameters:
message (input)
The handle for the message.
value (input)
The long integer to be written.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteShort – Write Short Integer

Interface:
xmsRC xmsBytesMsgWriteShort(xmsHMsg message,
                            xmsSHORT value,
                            xmsHErrorBlock errorBlock);

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

Parameters:
message (input)
The handle for the message.
value (input)
The short integer to be written.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteUTF – Write UTF String

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

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:
message (input)
The handle for the message.
value (input)
A character array containing the string to be written.
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
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

Reference topic

Terms of Use | Rate this page

Last updated: 24 May 2011

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