IBM Version 4 , Chapter 5. List APIs

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.

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.

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.

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.

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.

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.