In part 1 we discussed the basic concepts of Open List and Process Open List APIs. Now let's take a look at a sample program and see these APIs at work.
Listing job log messages in the background
This program illustrates the use of the Open List APIs, specifically the QGYOLJBL API, which lists job log messages. This API's asynchronous cousin is the QMHLJOBL API.
The program calls the QGYOLJBL API but does not request any entries, so the API will simply spawn-off the server job (if necessary) and immediately return. At this point, the program is free to do other things, if necessary.
Next, the program goes into a loop to process each message in the list that the server job is building. The QGYGTLE API is used to retrieve the messages from the server job (notice the do-until loop that embeds the call to the QGYGTLE API -- we'll discuss the rational for this later).
When the program is finished retrieving and displaying each message, it calls the QGYCLST API to close the list and free the associated resources.
Warning: You need library QGY in your library list
The Open List APIs and the APIs used to process open lists are in library QGY , not in QSYS where most of the other system APIs reside. The documentation doesn't mention this! So, make sure QGY is in your library list before calling any of the Open List APIs.
There are other open list processing APIs
QGYGTLE and QGYCLST are just two of the process open list APIs and the ones you will use most often. However, there other APIs used to manipulate and control open lists. For example, there is an API that you can use to control the attributes of the server job processing your list. See the System API Reference manual for more information on these and all the Open List APIs.
Bug alert
There was a slight problem that could occur when using the Get List Entry API (QGYGTLE ) in V4R2 or earlier. Sometimes when requesting the first entry of an open list, the QGYGTLE API indicated that it had returned records and yet did not return any data in the receiver parameter.
It's strictly a timing issue that is caused by calling the QGYGTLE API before the server job has time to start and run through its initiation code. The problem arises when the following two conditions are met:
1. You do not ask for any entries from the list API. Remember, the Open List APIs not only start the building of an open list, but they can also return entries (albeit it is optional). When you ask for at least one entry, the API is forced to wait until the server job starts and begins building the list, in effect eliminating the timing problem.
2. The QGYGTLE API is called too quickly after calling the Open List API. However, if you do not ask the Open List API to return any entries, it is possible to call the QGYGTLE API before the server job has time to start and run through its initiation code. This is the heart of the problem.
However, since the system was not compromised, and simple, effective workarounds existed, IBM never provided a PTF for the problem. A fix found its way into V4R3. However, other timing problems similar to this have been reported since. So keep the following workarounds in mind should you run into any of them.
The workarounds
There are two workarounds for the timing problems just discussed. The first is simple: Embed the call to the QGYGTLE API in a do-loop that loops until a record is returned. This is the approach our sample program uses. This workaround is best when your program has plenty to do between the time you call the Open List API and the first time you call the QGYGTLE API (e.g., perhaps your program opens a display file and asks for input from the user).
On the other hand, if your program is going to immediately ask for the first entry, then just ask the Open List API to return it. This eliminates one of the two conditions needed to cause the problem.
-----------------------------------
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.
