returned on this API call. If both values are the same, the API ret information.

Depending on the capabilities of your high-level language, some API use advantage of the following technique to avoid guessing the appropriate receiver variable:

1. Call

the API with a receiver variable length

of 8 bytes (that is

the

bytes available and the bytes returned

fields).

2. Dynamically allocate an amount of storage equivalent to the bytes a

3.Set the length of receiver variable parameter to the amount of st cated.

4.Pass the address of the storage allocated in step 2 by using p (directly).

This technique provides for highly flexible use of APIs that can retu amounts of data.

Keyed Interface

Some APIs have a keyed interface for selecting what

information

you

wa

returned. keyedA

interface

 

allows

the user

of

the

API

to

provide informatio

the

API

through

the use of keys. Keys are API-specific values that

 

that

a

certain

function should

be performed. Keys also are

used to

p

tion

to

an

API

or

to

retrieve

information

from an

API.

 

 

 

 

Through

the

use

of keys, you can be more selective;

you

can

choose

number of

items

rather

than

all

of them. For

example,

using

the

List

J

(QUSLJOB)

API,

you can receive selected information about a job base

keys

that

you

specify. If you want job

information about

the

output

you

only need to

specify

the

output

queue

priority

key.

 

 

 

The keys are typically supplied to an API and are passed to the API

variable-length record (there are some variableexceptions)-length record. A is a

collection of information that specifies the key being used and the d ciated with the key. If a given structure contains binary values, it aligned. “Defining Byte Alignment” on page 9-22 shows examples of correctl incorrectly defining byte alignment.

Some APIs that use variable-length records in addition to the List Job Change Object Description (QLICOBJD) API and the Register Exit Point (QUSRGPT, QusRegisterExitPoint) API. You can use the appropriate include member QUS in the system include (QSYSINC) library when you have variab length records as either input or output.

A keyed interface provides an easy-to-use means for later enhancing an without affecting the user who chooses not to use the enhancements. Fo ples that use a keyed interface, see “Using Keys with List Spooled API—Example” on page 3-24 (OPM RPG) and “Keyed Interface—Example” on page 4-3 (ILE C).

2-24System API Programming V4R1

Page 44
Image 44
IBM Version 4 manual Keyed Interface, Qusljob API