Bytes available and bytes returned fields

The bytes available field contains the length in bytes of all the data that is available to be returned to the user. The bytes returned field contains the length in bytes of all the data that is actually returned to the user.

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 can check the values for both the bytes available and bytes returned fields. If the value of the bytes available field is greater than the value of the bytes returned field, the API has more information to return than what can fit in the receiver variable. This might occur, over time, because the APIs that you use might be enhanced with new releases. The API might 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 is returned on this API call. If both values are the same, the API returns 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 the receiver variable parameter to the amount of storage allocated.
4. Call the API a second time with the re-allocated, larger receiver variable.

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