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.
What the API does
The Open List of Activation Group Attributes (QWVOLAGP) API builds a list of activation groups and their attributes for the specified job. The API is a Process Open List API, meaning it builds the list in the background (i.e., in another job/thread). This means that your program can go on and do something else while the system builds the list. It can later retrieve the list entries using the QGYGTLE API (see "The Open List APIs make list processing simpler and more efficient" (part 1 and part 2 for details on the Process Open List APIs including the QGYGTLE API).
Information the QWVOLAGP API generates
Each entry in the list of activation groups will contain the following information:
Activation group name -- char(10). For the default activation group, this field will contain *DFTACTGRP. For unnamed activation groups, it will be *UNNAMED.
Activation group number -- int(4). An internal number used by the system to uniquely identify the activation group within the job. You can use it, for example, with the QWVOLACT API to get more information on the activation group (e.g., which programs and service programs are currently activated within the activation group).
Number of activations -- int(4). The number of programs and service programs which are currently activated within the activation group.
Number of heaps -- int(4). The number of heaps existing in the activation group.
Static storage size -- int(4). The number of bytes of static storage – the most prevalent type of storage on most AS/400-iSeries – allocated to the activation group. You may want to use this figure in a garbage collecting program that reclaims activation groups which have large amounts of static storage allocated.
Heap storage size -- int(4). Same as static storage size above, except substitute "heap" for "static."
Root program name -- char(10). The name of the program that caused the activation group to be created. This field will be blank if the activation group is the default activation group. In the event the program object has been deleted or replaced, this field will contain *N.
Root program library -- char(10). The library of the root program. This field will be blank if the activation group is the default activation group. In the event the program object has been deleted or replaced, this field will contain *N.
Root program type-- char(1). This field will contain one of the following values:
N Program has been deleted or replaced.
0 Root program is an ILE program (i.e., *PROGRAM).
1 Root program is a service program (i.e., *SRVPGM).
2 Root program is a Java program.
blank The activation group is the default activation group.
Activation group state -- char(1). 0 if the activation group is in the user state. 1 if the activation group is in the system state.
Shared activation group indicator -- char(1). 0 if the activation group is not shared by other jobs. 1 if the activation group is shared by other jobs, which can happen in multithreaded applications.
In-use indicator -- char(1). 0 if the activation is not in use and, hence, is eligible to be reclaimed. 1 if the activation group is in use.
In the next installment, we'll discuss the parameters for this API and take a look at it in action.
-----------------------------------
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.
