Problem solve Get help with specific problems with your technologies, process and projects.

Open-list API provides crucial information on activation groups -- part 2

One of the many Open List APIs gives programs the ability to determine which activation groups are active in the job and allows the program to retrieve the activation groups' attributes. It can also provide the same information on activation groups in another job. This information can be crucial to programs that, for example, are designed to end other activation groups or are multi-threaded. 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.


Ron Turull
One of the many Open List APIs gives programs the ability to determine which activation groups are active in the job and allows the program to retrieve the activation groups' attributes. It can also provide the same information on activation groups in another job. This information can be crucial to programs that, for example, are designed to end other activation groups or are multi-threaded.

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.

More Information

Understanding the API's parameter list

The parameters to the QWVOLAGP API are fairly simple, and are as follows:

  • Receiver -- char(*). This is a data structure that should contain the fields described in part 1 in the section titled Information the QWVOLAGP API generates." If you don't want the API to wait for the first entry, this parameter is ignored. If you ask for multiple entries, this parameter can be an array of data structures.

  • Length of receiver -- int(4). The length in bytes of the Receiver parameter.

  • List information -- char(80). Data structure containing information about the list that the API will build and the entry(ies) the API will return. For example, it contains the list handle, a 4-character subfield uniquely identifying the list; you use this subfield with the QGYGTLE and QGYCLST APIs. It also contains a list status subfield containing one of the following values:

    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.

  • Number of records to return -- int(4). Set this field to zero if you do not want to wait for the first entry.

  • Format name -- char(8). Set this parameter to RAGA0100.

  • Qualified job name -- char(26). Use * to indicate that you want the activation groups for the job in which the program calling the API is running. If you want the activation groups for another job, specify the qualified job name.

  • Internal job identifier -- char(16). Use this parameter, if you want to specify the job using an internal job identifier, which you must get from one of the job information APIs. If you specify the job using the qualified job name, leave this parameter blank.

  • Error code -- char(*). Standard API error code.

    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.

    Two reminders

    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.


  • This was last published in January 2006

    Dig Deeper on Business-to-business (EDI, UCCnet)

    Start the conversation

    Send me notifications when other members comment.

    Please create a username to comment.

    -ADS BY GOOGLE

    SearchDataCenter

    Close