Filter
Top Products
returned on this API call. If both values are the same, the API returned all the
information.
Depending on the capabilities of your high-level language, some API users take
advantage of the following technique to avoid guessing the appropriate size for the
receiver variable:
1. Call the API with a receiver variable length of 8 bytes (that is, just enough for
the bytes available and the bytes returned fields).
2. Dynamically allocate an amount of storage equivalent to the bytes available.
3. Set the length of receiver variable parameter to the amount of storage allo-
cated.
4. Pass the address of the storage allocated in step 2 by using pass by value
(directly).
This technique provides for highly flexible use of APIs that can return variable
amounts of data.
Keyed Interface
Some APIs have a keyed interface for selecting what information you want
returned. A keyed interface allows the user of the API to provide information to
the API through the use of keys. Keys are API-specific values that inform the API
that a certain function should be performed. Keys also are used to pass informa-
tion to an API or to retrieve information from an API.
Through the use of keys, you can be more selective; you can choose one item or a
number of items rather than all of them. For example, using the List Job
(QUSLJOB) API, you can receive selected information about a job based on the
keys that you specify. If you want job information about the output queue priority,
you only need to specify the output queue priority key.
The keys are typically supplied to an API and are passed to the API using a
variable-length record (there are some exceptions). A variable-length record is a
collection of information that specifies the key being used and the data that is asso-
ciated with the key. If a given structure contains binary values, it must be 4-byte
aligned. “Defining Byte Alignment” on page 9-22 shows examples of correctly and
incorrectly defining byte alignment.
Some APIs that use variable-length records in addition to the List Job API are the
Change Object Description (QLICOBJD) API and the Register Exit Point
(QUSRGPT, QusRegisterExitPoint) API. You can use the appropriate include file in
member QUS in the system include (QSYSINC) library when you have variable-
length records as either input or output.
A keyed interface provides an easy-to-use means for later enhancing an API
without affecting the user who chooses not to use the enhancements. For exam-
ples that use a keyed interface, see “Using Keys with List Spooled Files
API—Example” on page 3-24 (OPM RPG) and “Keyed Interface—Example” on
page 4-3 (ILE C).
2-24 System API Programming V4R1