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 information 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 associated with the key. If a given structure contains binary values, it must be 4-byte aligned.
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 examples that use a keyed interface, see Example: Using keys with List Spooled Files API and Example: Keyed interface using ILE APIs.