IBM Version 4 manual User Space Alternative, Using a Continuation Handle, Qlicobjd API

User Space Alternative

Although a receiver variable is usually used for returning information API, sometimes a user space should be used instead. If the number

information		being returned			is	not known		or is	large, a user space is
can	create a		user	space	so	that	it	can	automatically	extend	up to
to	accommodate		the	information		being	retrieved.
The disadvantage of using a						receiver variable when it may be too
amount of data being returned is that the									API must be	called	again
remaining		data.

For an example of using a user space to return information from a r “Retrieving a File Description to a User Space—ILE C Example” on page

Related Information

ŸFor a discussion of variable-length structures using ILE C, see “Va Structure—Example” on page 4-3.

ŸFor an example using the Register Exit Point (QusRegisterExitPoint) AP

“Register Exit Point and Add Exit Program—ILE C Example” on page 4-9.

Ÿ	For	an example using the Change Object					Description		(QLICOBJD)		API
	see	“Program for Packaging a Product—OPM					RPG Example”		on	page A-3.
	The	change	object	information	parameter		is defined as the COBJI
	this	field	is later used by the			QLICOBJD		API.
Ÿ	For	a discussion of		include	files,	see	“APIs	and	the	QSYSINC	Libra

page 2-28.

Continuation Handle

Some

APIs

that

return information offer

a

continuation handle. A

handle

is

a

value

that

is

passed

between

a

high-level

language progr

API. It

is

used

to

mark

the

last

value

put

in

either

the receiver

space. When

a

call

to

an

API

is

made

and

the

API has

more

informat

than

what

could

fit

in

the receiver

variable

or user

space

provide

API returns a continuation handle. If a continuation handle is returned because there is more information to return, the caller can then ca and pass the continuation handle that was returned. The API continues

information

from

the

point that

it left off

on

the call

that

generat

handle.

When

you

use

the

continuation

handle

parameter,

that

is

the

only

par

can

change. All

other parameters must

appear

as

they

did on

the

ca

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 at the retrieve operation.

2. Call the API to retrieve the information.

3. Make use of the information returned.

Chapter 2. Getting Started with2-25APIs