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

StreamMessage

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

The contents of the body are written to 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.

Related reference
Stream messages

Functions

Summary of functions:
Function Description
xmsStreamMsgReadBoolean Read a boolean value from the message stream.
xmsStreamMsgReadByte Read a signed 8-bit integer from the message stream.
xmsStreamMsgReadBytes Read an array of bytes from the message stream.
xmsStreamMsgReadBytesByRef Get a pointer to an array of bytes in the message stream, and get the length of the array.
xmsStreamMsgReadChar Read a 2-byte character from the message stream.
xmsStreamMsgReadDouble Read an 8-byte double precision floating point number from the message stream.
xmsStreamMsgReadFloat Read a 4-byte floating point number from the message stream.
xmsStreamMsgReadInt Read a signed 32-bit integer from the message stream.
xmsStreamMsgReadLong Read a signed 64-bit integer from the message stream.
xmsStreamMsgReadObject Read a value from the message stream, and return its data type.
xmsStreamMsgReadShort Read a signed 16-bit integer from the message stream.
xmsStreamMsgReadString Read a string from the message stream.
xmsStreamMsgReset Put the body of the message into read-only mode and reposition the cursor at the beginning of the message stream.
xmsStreamMsgWriteBoolean Write a boolean value to the message stream.
xmsStreamMsgWriteByte Write a byte to the message stream.
xmsStreamMsgWriteBytes Write an array of bytes to the message stream.
xmsStreamMsgWriteChar Write a character to the message stream as 2 bytes, high order byte first.
xmsStreamMsgWriteDouble 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.
xmsStreamMsgWriteFloat Convert a floating point number to an integer and write the integer to the message stream as 4 bytes, high order byte first.
xmsStreamMsgWriteInt Write an integer to the message stream as 4 bytes, high order byte first.
xmsStreamMsgWriteLong Write a long integer to the message stream as 8 bytes, high order byte first.
xmsStreamMsgWriteObject Write a value, with a specified data type, to the message stream.
xmsStreamMsgWriteShort Write a short integer to the message stream as 2 bytes, high order byte first.
xmsStreamMsgWriteString Write a string to the message stream.

xmsStreamMsgReadBoolean – Read Boolean Value

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

Read a boolean value from the 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 call 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

xmsStreamMsgReadByte – Read Byte

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

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

Parameters:
message (input)
The handle for the message.
value (output)
The byte that is read. If you specify a null pointer on input, the call 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

xmsStreamMsgReadBytes – Read Bytes

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

Read an array of bytes from the message stream.

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 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 xmsStreamMsgReadBytes() 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 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
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsStreamMsgReadBytesByRef – Read Bytes by Reference

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

Get a pointer to an array of bytes in the message stream, and get the length of the array.

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.
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
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsStreamMsgReadChar – Read Character

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

Read a 2-byte character from the message stream.

Parameters:
message (input)
The handle for the message.
value (output)
The character that is read. If you specify a null pointer on input, the call 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

xmsStreamMsgReadDouble – Read Double Precision Floating Point Number

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

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

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 call 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

xmsStreamMsgReadFloat – Read Floating Point Number

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

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

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 call 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

xmsStreamMsgReadInt – Read Integer

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

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

Parameters:
message (input)
The handle for the message.
value (output)
The integer that is read. If you specify a null pointer on input, the call 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

xmsStreamMsgReadLong – Read Long Integer

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

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

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 call 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

xmsStreamMsgReadObject – Read Object

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

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

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

xmsStreamMsgReadShort – Read Short Integer

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

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

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 call 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

xmsStreamMsgReadString – Read String

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

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

xmsStreamMsgReset – Reset

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

Put the body of the message into read-only mode and reposition the cursor at the beginning of the 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
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsStreamMsgWriteBoolean – Write Boolean Value

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

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

xmsStreamMsgWriteByte – Write Byte

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

Write a byte to the 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

xmsStreamMsgWriteBytes – Write Bytes

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

Write an array of bytes to the 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

xmsStreamMsgWriteChar – Write Character

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

Write a character to the 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

xmsStreamMsgWriteDouble – Write Double Precision Floating Point Number

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

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

xmsStreamMsgWriteFloat – Write Floating Point Number

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

Convert a floating point number to an integer and write the integer to the 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

xmsStreamMsgWriteInt – Write Integer

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

Write an integer to the 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

xmsStreamMsgWriteLong – Write Long Integer

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

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

xmsStreamMsgWriteObject – Write Object

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

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

Parameters:
message (input)
The handle for the message.
value (input)
An array of bytes containing the value to be written.
length (input)
The number of bytes in the array.
objectType (input)
The data type of the value, which must be one of the following objecttypes:
  • 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

xmsStreamMsgWriteShort – Write Short Integer

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

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

xmsStreamMsgWriteString – Write String

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

Write a string to the message stream.

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

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