A receiver variable is a program variable that is used as an output field to contain information that is returned from an API.
Retrieve 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 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 may have one or many formats that give you the flexibility to choose the information that you need. To see examples of using receiver variables, see Scenario: Original Program Model (OPM) API.
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 Example: Receiver variables using ILE APIs.
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.