Continuation handle

When a call to an API is made and the API has more information to return than what can fit in the receiver variable or the user space, the API returns a continuation handle, which is used to mark the last value put in the receiver variable or the user space.

If a continuation handle is returned to the caller because there is more information to return, the caller can call the API again and pass the continuation handle that was returned. The API continues to return information from the point 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.

To use a continuation handle, follow these steps:

Blank out the continuation handle to let the API know that this is a first attempt at the retrieve operation.
Call the API to retrieve the information.
Use the information returned.
If the continuation handle field in the receiver variable is not set to blanks, do the following steps until the continuation handle equals blanks:
1. Copy the continuation handle from the receiver variable to the continuation handle parameter.
2. Call the API again by using the continuation handle that was returned. Keep all other parameters the same as in the original API call.

For a program example that uses a continuation handle, see Example in ILE C: Retrieving exit point and exit program information.