Filter
Top Products
Receiver Variables
Some APIs use receiver variables to place returned information. For example,
instead of using a user space to return the information, the information is placed in
a receiver variable. A retrieve API requires only addressability to storage of fixed
size (typically a field or structure defined in your program), whereas a list API
requires a user space because the amount of information returned by a list API
may be large and not of a predictable size.
Retrieve APIs that return information to a receiver variable use the storage provided
for the receiver variable parameter. The returned information is in a specific format.
The format name is usually a parameter on the call to the API, and the format indi-
cates to the API the information that you want returned. On the return from the call
to the API, the caller parses through the receiver variable and extracts the informa-
tion that is needed. The caller knows how the information is returned by the docu-
mented format of the information. An API may have one or many formats that give
you the flexibility to choose the information that you need. Chapter 3, “Common
Information across APIs—Basic (OPM) Example” on page 3-1 contains several
examples of using receiver variables.
Some formats have variable-length fields, some only fixed-length fields, and yet
others have repeating entries. To move through the information, some formats use
offsets, some use lengths, and some use displacements. When the field is defined
as an offset, the offset is always the number of bytes from the beginning of the
receiver variable. When a length or displacement is used to move through the
receiver variable entries, the length is always added to the current position within
the receiver variable. For examples of repeating entry types and the various ways
to move through receiver variable entries, see “Receiver Variables—Examples” on
page 4-7.
Offsets and displacements are not the same. An offset is relative to the beginning
of a receiver variable or the beginning of a user space, whereas a displacement is
relative to the current position of the pointer plus the value within the displacement
field. If a format uses a displacement, you will see the word displacement in the
Field
column of the API description.
Bytes Available and Bytes Returned Fields
Most formats used by retrieve APIs have a bytes available field and a bytes
returned field. The bytes available field contains the length in bytes of all the data
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 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
Chapter 2. Getting Started with APIs 2-23