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

C functions that return a byte array by value

This topic describes the interface used by C functions that return a byte array by value.

In the C API, certain functions return a byte array as a parameter. Each of these functions uses the same interface for retrieving a byte array. The following example written in C code illustrates the function, xmsGetByteArrayProperty() in the PropertyContext class:
xmsRC xmsGetByteArrayProperty(xmsHObj object
                              xmsCHAR *propertyName,
                              xmsSBYTE *propertyValue,
                              xmsINT length,
                              xmsINT *actualLength
                              xmsHErrorBlock errorBlock) const;
Three parameters control the retrieval of a byte array:
propertyValue
This parameter is a pointer to a buffer provided by the application into which XMS copies the bytes in the array.
length
This parameter is the length of the buffer in bytes. This is an input parameter that must be set by the application before the call. If you specify XMSC_QUERY_SIZE instead, the byte array is not returned, but its length is returned in the actualLength parameter.
actualLength
This output parameter is the number of bytes in the array that XMS copies into buffer. If you specify a null pointer for this parameter on input, the length of the array is not returned.

If the buffer is not large enough to store the whole array, XMS returns the array truncated to the length of the buffer, sets the actualLength parameter to the length of the whole array, and returns an error.

Two functions, xmsBytesMsgReadBytes() and xmsStreamMsgReadBytes(), have a slightly different interface. Using one of these functions, an application can retrieve a byte array in stages by successive calls to the function. Each call reads bytes into the buffer provided by the application starting from the current position of an internal cursor, and an output parameter, returnedLength, to determine how many bytes have been read into the buffer. Neither function has the equivalent of the actualLength parameter in its interface, but an application can specify XMSC_QUERY_SIZE to determine the number of bytes remaining in an array starting from the current position of the cursor.


Concept topic

Terms of Use | Rate this page

Last updated: 24 May 2011

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