Bytes available and bytes returned fields

All available data is returned if enough space is provided in the receiver variable. If the size of the receiver variable is at least large enough to contain all of the data, the bytes returned field equals the bytes available field. If the receiver variable is not large enough to contain all of the data, the bytes available field contains the number of bytes that can be returned.

Your code could check the values for both the bytes available and bytes returned fields. If the bytes available field is greater than the bytes returned field, the API had more information to return than what would fit in the receiver variable. This could occur, over time, because the APIs that you use may be enhanced with new releases. The API may also have more information to return if the receiver variable is being used to return a variable-length field (or array) and a very large value was returned on this API call. If both values are the same, the API returned all the information.

Depending on the capabilities of your high-level language, some API users take advantage of the following technique to avoid guessing the appropriate size for the receiver variable:

1. Call the API with a receiver variable length of 8 bytes (that is, just enough for the bytes available and the bytes returned fields).
2. Dynamically allocate an amount of storage equivalent to the bytes available.
3. Set the length of receiver variable parameter to the amount of storage allocated.
4. Pass the address of the storage allocated in step 2 by using pass by value (directly).

This technique provides for highly flexible use of APIs that can return variable amounts of data.