Filter
Top Products
Chapter 5. List APIs
This chapter contains an overview of list APIs, which are those APIs that return a
list unique to a given API. The chapter discusses the characteristics of a list API
and provides information that you should be aware of when you use list APIs.
The List Objects That Adopt Owner Authority (QSYLOBJP) API is referred to
throughout this chapter. The QSYLOBJP API is included in “List Objects That
Adopt Owner Authority API—Example” on page 5-12 if you need to refer to it as
you read this chapter.
Characteristics of a List API
As discussed in “User Spaces” on page 2-13, list APIs return information to a user
space. List APIs generally have a user space parameter that uses a general (or
common) data structure. You must use the general data structure to get at the
information placed in the user space by the list API.
General Data Structure
This topic describes some of the more important fields that comprise the general
data structure. Figure 5-1 on page 5-2 shows the common fields that list APIs
use. All list APIs have an input parameter section, a header section, and a list data
section.
User Area
The first field in the general data structure is called the user area. This is a 64-byte
field that is not used or changed by the system. Whatever information you place in
this field remains there. For example, you may specify the date last used, include
comments about the list, and so forth.
Size of Generic Header
The size of the generic header does not include the size of the user area. All
sections have a size, which may differ for each API.
Some fields may be added to the generic header from release to release. Because
fields may be added, you may want to check the size of this field. If your applica-
tion works across multiple releases, it is recommended that you check the size of
this field to determine which fields are applicable.
Offset to Input Parameter Section
The offset to input parameter section is an offset to the start of the input parameter
section. The input parameter section may contain a copy of the input parameters
that you pass to the list API. The QSYLOBJP API's input parameter section is
shown on page 5-14.
The input parameter section contains a copy of the continuation handle value that
you passed as the continuation handle parameter to the API. “Other Fields of
Generic Header” on page 5-3 discusses continuation handles further.
Copyright IBM Corp. 1997 5-1