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

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


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.

    Requires Free Membership to View

    Login

    Register today to access targeted resources from our editorial writers and independent industry experts including news, tips, and advice to help you do your job more efficiently and effectively. Stay informed on the hottest topics and biggest challenges faced by IT professionals working with iSeries products and services.

    By submitting your registration information to Search400.com you agree to receive email communications from TechTarget and TechTarget partners. We encourage you to read our Privacy Policy which contains important disclosures about how we collect and use your registration and other information. If you reside outside of the United States, by submitting this registration information you consent to having your personal data transferred to and processed in the United States. Your use of Search400.com is governed by our Terms of Use. You may contact us at webmaster@TechTarget.com.

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 first published in January 2006

    • Disclaimer: Our Tips Exchange is a forum for you to share technical advice and expertise with your peers and to learn from other enterprise IT professionals. TechTarget provides the infrastructure to facilitate this sharing of information. However, we cannot guarantee the accuracy or validity of the material submitted. You agree that your use of the Ask The Expert services and your reliance on any questions, answers, information or other materials received through this Web site is at your own risk.

    Back to top