List sections

Each list API provides an input parameter section, a header section, and a list data section.

Table 1. List sections in a user space format
List Section Contents
Input parameter section An exact copy of the parameters coded in the call to the API. In general, this section contains all the parameters available.
Header section Parameter feedback and global information about each object. Some APIs do not use this section; in those cases, the value of the size-of-header-section field is zero.
List data section The generated list data. All entries in the list section are the same length.

When you retrieve list entry information from a user space, use the allocated size defined in your application. To get the next entry, use the entry size returned in the generic header. The size of each entry might be padded at the end. If you do not use the entry size from the generic header, the result might not be valid.

Partial list considerations

Some APIs might be able to return more information to the application than fits in a receiver variable or a user space. The information returned is correct, but not complete.

If the list information is not complete, the first situation and possibly the second situation occur:

  • A P is returned in the information status field of the generic user space layout.
  • The API supports a continuation handle.

If an indicator of a partial list is returned and the API supports a continuation handle, the application should call the API again with the continuation handle in the list header section and specify that the list begins with the next entry to be returned.

Note: If this is the first time that the API attempts to return information, the continuation handle must be set to blanks. If the API does not support a continuation handle, you need to call the API again and to use more restrictive values for the parameters.