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:

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.
Make use of 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 is returned. Keep all other parameters the same as the original API call.