IBM Version 4 manual Receiver Variables, Bytes Returned Fields, Beginning, API description

Receiver Variables

Some APIs use receiver variables to place

returned

information. For

ex

instead

of

using

a

user

space

to

return

the

information,

the

informa

a receiver variable. A retrieve API requires

only

addressability

to

size (typically a field or structure defined

in

your program),

wher

requires

a

user

space

because

the amount

of

information

returned

b

may be large and not of a predictable size.

Retrieve

APIs

that

return

information

to

a

receiver

variable

use

the

for

the

receiver

variable

parameter. The

returned

information

is

in

The format name is usually a parameter

on

the

call

to

the

API, and

cates

to the API

the

information that

you

want returned. On the ret

to

the

API,

the

caller

parses

through

the

receiver

variable

and

ex

tion that is needed. The caller knows how

the

information

is

returned

mented

format

of

the

information. An

API

may

have

one

or

many

formats

you the flexibility to choose the information that you need. Chapter Information across APIs—Basic (OPM) Example” on page 3-1 contains severa

examples

of

using

receiver

variables.

Some formats have variable-length fields, some only

fixed-length

fields,

others have repeating entries. To move through the information, some f

offsets,

some

use

lengths,

and

some use

displacements. When

the

field

as an offset, the offset is always the number

of

bytes

from

the

receiver variable. When a length or displacement

is used to move thr

receiver

variable

entries,

the

length

is

always

added

to

the

curre

the

receiver

variable. For

examples

of

repeating

entry

types and

th

to move through receiver variable

entries, see

“Receiver

Variables—Ex

page

4-7.

Offsets

and

displacements

are

not

theoffset sameis. relativeAn

to

the

beginning

of a receiver variable or the beginning of a

udisplacementer space,is whereas

relative to the current position of the pointer

plus

the

value

within

field. If a format uses

a displacement, you will see

the

word

dis

Field

column

of

the

API description.

Bytes Available and	Bytes	Returned Fields
Most formats used by retrieve APIs have a bytes					available		field		a
returned field. The bytes available field contains the length in byt
available to be returned to the user. The bytes					returned		field		co
bytes of		all the data that is	actually	returned	to the user.
All	available data is returned if		enough	space is	provided		in	the
the	size of the receiver variable is at least				large	enough		to	co
the	bytes	returned field equals	the bytes available			field. If			the

not large enough to contain

all

of the

data, the

bytes available

fi

number

of

bytes

that

can

be

returned.

Your

code

could

check

the values for both the bytes available and

fields. If

the

bytes

available

field

is greater than the bytes r

had

more

information

to

return than what would fit in the receiver v

could

occur,

over

time,

because

the

APIs that you use may be enh

releases. The

API

may

also

have

more

information

to

return

if

the

re

is

being

used

to

return a

variable-length

field

(or

array)

and a

v

Chapter

2.

Getting

Started

with2-23

APIs