System Object Access APIs List

SOA enablers:

System Object Access also includes enablers (APIs), which applications can use to access data in system objects or to request graphical lists and attribute views of the object data. The APIs for manipulating lists of objects must be called in the correct order. The basic flow is as follows:

CreateErrorHandle -- Creates a handle to an "error" object
                     to be passed to other APIs
CreateListHandle -- Instantiates a list object on the client
OpenList -- Builds IBM i list associated with client
            list
(Manipulate the list and its objects using various generic
 and subclass APIs)
CloseList -- Closes list and release IBM i resource
DeleteListHandle -- Destroys list object on the client

The CWBSO_CreateListHandle API must be called to create a list before any other list APIs are called. The CWBSO_CreateListHandle API returns a list handle to the caller. The list handle must be passed as input to all other list APIs.

After the list is allocated, the CWBSO_SetListFilter API can be called to change the filter criteria for the list. CWBSO_SetListFilter is optional; if it is not called, the list will be built with the default filter criteria. Similarly, the CWBSO_SetListSortFields API can be called to define the attributes on which the list will be sorted. If it is not called the list will not be sorted.

The CWBSO_OpenList API must be called to build the list of objects. This results in a request that is sent to the system. The list is built on the system, and some or all of the objects (records) in the list are buffered down to the list on the client. Although all objects in the list are not necessarily cached on the client, the APIs behave as if they are. Once the CWBSO_OpenList API is called successfully, the following APIs can be called:

CWBSO_GetObjHandle

Retrieves a handle to a specific object in the list. The object handle can then be used to manipulate the specific object.

CWBSO_DeleteObjHandle

Releases the handle returned by CWBSO_GetObjHandle.

CWBSO_DisplayList

Displays the spreadsheet view of the list.

CWBSO_GetListSize

Retrieves the number of objects in the list.

CWBSO_CloseList

Closes the IBM® i list and destroys all client objects in the list. All object handles returned by CWBSO_GetListObject no longer are valid after the list is closed. After the list is closed, the APIs in this list cannot be called until the CWBSO_OpenList API is called again. The CWBSO_DeleteListHandle API should be called to destroy the list object.