In part 1, we discussed what the Open List of Activation Group Attributes (QWVOLAGP) API does and what information the API can return to your program. Now, let's look at how you go about using the API.
Understanding the API's parameter list
The parameters to the QWVOLAGP API are fairly simple, and are as follows:
0 The building of the list is pending.
1 The list is in the process of being built.
2 The list has been completely built.
3 An error occurred when building the list. The next call to the Get List
Entries (QGYGTLE) API will cause the error to be signaled to the caller of the QGYGTLE API.
4 The list is primed and ready to be built.
Sample program The example program shown LISTACTG.RPG illustrates the use of the QWVOLAGP API. This sample program is very similar to the example code we discussed back in December. The major changes are:
1. The QWVOLAGP API is substituted for the QGYOLJBL API.
2. The QWVOLAGP API waits for the first entry, whereas the QGYOLJBL API did not in the December example. This is by design (i.e., the QWVOLAGP API does not need to wait).
3. The information returned by the QWVOLAGP API is much simpler.
The program consists of three general parts. The first portion calls the QWVOLAGP API. The second part displays the activation group name and number, gets the next entry using the QGYGTLE API, then loops to process each entry in the list. The third and final portion of the program releases the resources used by the list by calling the QGYCLST (close list) API.
1. The open list APIs are in library QGY, not in QSYS where most of the other system APIs reside. The manual doesn't tell you that! So, make sure QGY is in your library list before calling any of the open list APIs.
2. There have been some slight timing problems with the QGYGTLE API (Get List Entry) over the years. For example, sometimes when requesting the first entry of an open list, the QGYGTLE API indicates that it has returned records and yet does not return any data in the receiver parameter.
It's strictly a timing issue that arises when two conditions are met:
1. You do not ask for any entries from the API that opens the list (QWVOLAGP in this case). Remember, the open list APIs not only start the building of an open list, they can also return the first entry(ies). This is optional.
2. The QGYGTLE API is called too quickly after calling the API that opens the list. 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.
When you ask for at least one entry from the API that opens the list, the API is forced to wait until the server job starts and begins building the list, in effect eliminating the timing problem. So, to avoid these timing issues, it is best to always request the first entry from the API that opens a list.
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.