Filter
Top Products
User Space Alternative
Although a receiver variable is usually used for returning information from a retrieve
API, sometimes a user space should be used instead. If the number of bytes of
information being returned is not known or is large, a user space is preferred. You
can create a user space so that it can automatically extend up to 16MB of storage
to accommodate the information being retrieved.
The disadvantage of using a receiver variable when it may be too small for the
amount of data being returned is that the API must be called again to receive the
remaining data.
For an example of using a user space to return information from a retrieve API, see
“Retrieving a File Description to a User Space—ILE C Example” on page A-11.
Related Information
For a discussion of variable-length structures using ILE C, see “Variable-Length
Structure—Example” on page 4-3.
For an example using the Register Exit Point (QusRegisterExitPoint) API, see
“Register Exit Point and Add Exit Program—ILE C Example” on page 4-9.
For an example using the Change Object Description (QLICOBJD) API in RPG,
see “Program for Packaging a Product—OPM RPG Example” on page A-3.
The change object information parameter is defined as the COBJI field, and
this field is later used by the QLICOBJD API.
For a discussion of include files, see “APIs and the QSYSINC Library” on
page 2-28.
Continuation Handle
Some APIs that return information offer a continuation handle. A continuation
handle is a value that is passed between a high-level language program and an
API. It is used to mark the last value put in either the receiver variable or the user
space. When a call to an API is made and the API has more information to return
than what could fit in the receiver variable or user space provided by the caller, the
API returns a continuation handle. If a continuation handle is returned to the caller
because there is more information to return, the caller can then call the API again
and pass the continuation handle that was returned. The API continues to return
information from the point that it left off on the call that generated the continuation
handle.
When you use the continuation handle parameter, that is the only parameter that
can change. All other parameters must appear as they did on the call to the API
that generated the continuation handle to obtain predictable results.
Using a Continuation Handle
To make use of a continuation handle, do the following:
1. Blank out the continuation handle to let the API know that this is a first attempt
at the retrieve operation.
2. Call the API to retrieve the information.
3. Make use of the information returned.
Chapter 2. Getting Started with APIs 2-25