General data structure for list APIs
The data structure for the list APIs consists of several fields.
The following data structure shows the common fields that the list APIs use. All list APIs have an input parameter section, a header section, and a list data section.
Header
*------------------------------------* *-------------------------*
+00| | | |
| 64-Byte User Area | | |
| | | |
*------------------------------------* *--->| Input Parameter Section |
+40| Size of Generic Header | | | |
*------------------------------------* | . .
| | | . .
| Generic Header | | *-------------------------*
| | | | |
| | |
+6C| Offset to Input Parameter Section -+----*
| | | |
+70| Input Parameter Section Size | *-------------------------*
| | | |
+74| Offset to Header Section-----------+-------->| Header Section |
| | | |
+78| Header Section Size | | |
| | | |
+7C| Offset to List Data Section--------+----* | |
| | | | |
+80| List Data Section Size | | | |
| | | . .
+84| Number of List Entries | | . .
| | | | |
+88| Size of Each Entry | | *-------------------------*
| | | | |
+8C| CCSID of data in the user space | |
| | |
+90| Country ID | | | |
| | | | List Data Section |
+93| Language ID | | |-------------------------*
| | *--->| Entry 1 |
+95| Subsetted list indicator | |-------------------------*
| | | Entry 2 |
+C0| API entry point name | |-------------------------*
| | | Entry 3 |
| | | |
*------------------------------------* . .
. .
| |
|-------------------------*
| Last Entry |
|-------------------------*
| |
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 can specify the date last used or include comments about the list.
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 might differ for each API.
Some fields might be added to the generic header from release to release. Because fields might be added, you might want to check the size of this field. If your application 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 the input parameter section is an offset to the start of the input parameter section. The input parameter section might contain a copy of the input parameters that you pass to a list API. For an example, see Input Parameter Section in List Objects That Adopt Owner Authority (QSYLOBJP) API.
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 discusses continuation handles further.
Offset to header section
The header section includes an offset to where the header section starts and the size of the header section. This section is needed in the event any input parameters have a special value. The fields in the header section tell what the special value resolved to. For example, the special value *CURRENT for the user name parameter would resolve to the user profile name for the job that called the API.
This section is also sometimes used for API-specific control information that is not related to a particular list entry.
For an example, see Header Section in List Objects That Adopt Owner Authority (QSYLOBJP) API.
Offset to list data section
The offset to the list data section is the offset to the start of the format. The specific format that the API uses is determined by the name you specify for the format name parameter. The specific format that you use determines what information is returned in the user space.
The number of list entries field tells how many entries have been returned to you.
The size of each entry field within the list data section tells how large each entry is. In the list data section, each entry is of the same length for a given list. If the size of each entry field is 0, the entries have different lengths and the format tells the length of each entry.
The list data sections for the QSYLOBJP API are shown in the OBJP0100 Format, OBJP0110 Format, and the OBJP0200 Format. This API has three possible formats.
For more information about formats and how to extract a field from a format, see Format and Extracting a field from the format.
Other fields of generic header
The field called structure's release and level is part of the generic header. This field describes the layout of the generic header. For a program-based API, this value should be 0100. For a service-program-based API, the value should be 0300.
The information status field tells you whether the information in the user space is complete and accurate, or partial. You need to check the value of this field before you do anything with the information in the user space, shown at (1) in the RPG example program. Possible values for this field follow.
| Status value | Description |
|---|---|
| C | Complete and accurate. |
| I | Incomplete. The information you received is not accurate or complete. |
| P | Partial but accurate. The information you received is accurate, but the API had more information to return than the user space could hold. |
If the value is P, the API has more information to return than what could fit in the user space. If you received the value P, you need to process the current information in the user space before you get the remaining information. The API returns a continuation handle usually in the form of a parameter. You can use this continuation handle value to have the remaining information placed in the user space. You specify the continuation handle value that the API returned as the value of the continuation handle input parameter on your next call to the API.
The QSYLOBJP API provides a continuation handle in the header section to return the remaining information to the user space, as shown at (2) in the RPG example program. The user then passes this value back to the API as an input parameter so that the API can locate the remaining information and place it in the user space, as shown at (3) in the RPG example program.
If the API does not have a continuation handle and the information status field value is P, you must further qualify what you want in the list. In other words, you must be more specific on the parameter values that you pass to the API. For example, the QUSLOBJ API asked to get a list of objects; however, all of the objects on the system would not fit in the user space. To further qualify or limit the number of objects returned, the user might specify all libraries that start with a specific letter.