Receiver variables

A receiver variable is a program variable that is used as an output field to contain information that is returned from a retrieve API.

Retrieve APIs use receiver variables rather than user spaces to place returned information. A retrieve API requires only addressability to storage of fixed size (typically a field or structure defined in your program). A list API, in comparison, requires a user space because the amount of information returned by a list API might be large and not of a predictable size.

Retrieve APIs that return information to receiver variables 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 indicates 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 information that is needed. The caller knows how the information is returned by the documented format of the information. An API might have one or many formats that give you the flexibility to choose the information that you need.

Some formats have variable-length fields, some have only fixed-length fields, and some 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.

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 see the word displacement in the Field column of the API description.