In the past we have looked at a few API lists -- APIs whose output is a list of entries that are written to a user space -- (for example, the QMHLJOBL API). One of its drawbacks, however, is that it can be painfully asynchronous -- your program has to wait for the entire list of entries to be produced and written to the user space before it can access any of them or do anything else for that matter. Wouldn't it be nice if a program could start accessing the first entries while the rest of the list is still being produced? With the Open List and Process Open List APIs, that is now possible.
Open lists
With the Process Open List APIs, OS/400-i5/OS has the ability to build lists in the "background" (i.e., in a spawned-off batch job and/or thread). When it does so, it is called an open list.
You can request a list be built in the background by calling the special Open List version of the list-API you would normally use; however, not all the list-APIs have an open-list version. Here are just a few of the Open List APIs available:
QGYOLJBL: Starts an open list of job log messages. Open list version of the QMHLJOBL API.
QGYOLMSG: Starts an open list of messages. Open list version of the QMHLSTM API.
QGYOLOBJ: Starts an open list of objects. Open list version of the QUSLOBJ API.
QGYRPRTL: Starts an open list of printers. No related API.
QGYOLSPL: Starts an open list of spooled files. Open list version of the QUSLSPL API.
The above APIs represent the longer running list-APIs. They all either:
Have the potential of building lists with many (e.g., thousands of) entries; and/or
Generate entries that are complex and take a relatively long time to build.
There are many other Open-List APIs and arguably some of them have the same potential. To find other Open-List APIs, search the API documentation for the phrase "open list." Also keep in mind, if you cannot find an Open-List API to meet your needs and you are savvy enough, you should be able to implement your own version of background list building using threads.
The parameters of most Open List APIs are similar to their "asynchronous" counterparts. The only real difference is an additional informational data structure parameter in which the API returns information you'll will need later when requesting list entries (e.g., one of the subfields of this data structure is a handle that you use to identify the list).
How to use the Open List APIs
After locating the documentation for the Open List API that you want, the first thing you do is call it. All the Open List APIs do two things:
1. Start the building of the open list. If an "open-list-building" batch job/thread (called a server job) is not available, one is started.
2. Return list entries. The APIs can optionally return one or more list entries. You can request any number of entries, but it is best to at most request only the first few.
Once the list starts building in background, your application is free to do other things. When you need an entry from the list, you call the Get Open List Entry API (QGYGTLE). You can request any number of entries at one time.
The list remains open (i.e., available) for as long as you like. You can request the entries in any order, and you can reread entries. When you are finished with the list, you call the Close List API (QGYCLST). This frees the resources in your job (the list is built in a space in the "client" job, not the server job) that were used to produce the list; however, closing the list does not end the server job. The server job remains active to service other open-list requests by the same job. The server job automatically ends when the "client" job ends.
In my next installment, we'll look at an example of using the Open-List APIs.
-----------------------------------
About the author: Ron Turull is editor of Inside Version 5. He has more than 20 years' experience programming for and managing AS/400-iSeries systems.
