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

Commands, APIs and op-codes to control activation groups

Ron Turull takes a look at some of the more common system commands, APIs and high level language op-codes to control activation groups.

In the last two administrator tips -- Understanding the ins-and-outs of activation groups -- Part I and Understanding the ins and outs of activation groups -- Part II -- we discussed activation groups in some detail. Let's look now at some of the more common system commands, APIs and high level language op-codes (a.k.a. HLL verbs) you can use to control activation groups.

RCLACTGRP command
The RCLACTGRP CL command (Reclaim Activation Group) is used to delete a specific or all eligible activation groups. An eligible activation group is one that is not being used. That is, there is no program running in it. Therefore, you must execute the RCLACTGRP command from outside the activation group you want to delete (i.e., from within another activation group). Deleting an activation group frees up all the resources it has allocated. Those resources are then given back to the system to use somewhere else.


Ron Turull

RCLRSC command
Beware, the Reclaim Resources CL command does not affect activation groups. That means you cannot delete an activation group with it. In fact, it doesn't do anything when used in an ILE activation group. It only affects –- and should only be used in -– the default activation group. There, it will operate as usual for OPM programs. However, for ILE programs running in the default activation group, it's a bit tricky.

For an ILE program that was created with one of the CRTBNDxxx commands using the DFTACTGRP(*YES) option, the RCLRSC command will free static storage and close files. However, if the ILE program was not created with one of the CRTBNDxxx commands using the DFTACTGRP(*YES) option and it was running in the default activation group, the reclaim resources command will reinitialize -– but not free –- the program's static storage, and it will not close any files the program opened. The consequence of this can be huge: The next time the program is called, it will open the files again, creating another set of open data paths. The old ODPs are not reused; they essentially become resource-sucking garbage that cannot be reclaimed without ending the job. That is because they are in the default activation group, which can be deleted (i.e., reclaimed) only by ending the job.

WRKJOB command
Option 18 on the Work with Job display will show you a list of the activation groups that exist for a particular job. It will show you the name of the activation group as well as whether it is in use. When *NO is shown in the In Use Indicator column, the corresponding activation group is eligible for deletion by the RCLACTGRP command.

CEE4FCB API
The Find a Control Boundary API retrieves information about the nearest control boundary. A control boundary is any ILE program or procedure that was called from a program or procedure running in another activation group. In the default activation group, a control boundary is any ILE program that is called by an OPM program.

The CEE4FCB API retrieves two pieces of information. In the first parameter, the API returns the number of call entries away the nearest control boundary is, relative to the caller of the API. So, for example, if the program calling the CEE4FCB is a control boundary, the API will return 0. If the program calling the CEE4FCB was called by a control boundary program, the API will return 1. And so on.

In the second parameter, the API will return a 0 if the nearest control boundary is a hard control boundary (the oldest call stack entry in the activation group or, in other words, the first program called in the activation group). The second parameter will be a 1 if the control boundary is a soft control boundary.

CEETREC and CEE4ABN APIs
The End Activation Group Normally API (CEETREC) and the End Activation Group Abnormally API (CEE4ABN) immediately end all ILE programs and procedures up to and including the nearest control boundary program/procedure. If the nearest control boundary is a hard control boundary, then the associated activation group is also destroyed.

However, if the nearest control boundary is a soft control boundary, then the associated activation group will not be deleted; only the programs going back on the call stack up to and including the soft control boundary will be deleted.

HLL end verbs
High level language end verbs are language op-codes that do the same thing as the CEETREC and CEE4ABN APIs. In ILE C, the end verb is the exit() function. In ILE COBOL, the end verb is the STOP RUN statement. ILE RPG does not have an end verb (setting indicator LR on is not the equivalent of an end verb); use the CEETREC or CEE4ABN API.

CEE4RAGE API
The Register Activation Group Exit Procedure API lets you establish an ILE procedure that the system will call before the activation group ends. This exit procedure will be called right before any open files are closed and before the activation group resources are returned to the system. You can register multiple exit procedures for the same activation group; they will be called in LIFO order. You cannot call the CEE4RAGE API from within the default activation group.

Call operations
Activation groups (other than the default activation group) are created only as a result of a program calling an ILE program or an ILE procedure in a service program. The system queries the activation group attribute of the called ILE program or service program and determines whether an activation group needs to be created based on the activation group attribute stored in the program or service program as follows:

  • *CALLER. No activation group needs to be created. The called program or service program will run in the same activation group as the caller.
  • *NEW. An activation group will be created each and every time the program is called. Service programs cannot have this attribute.
  • *DFTACTGRP. No activation group needs to be created. The called program or service program will run in the default activation group.
  • Activation group name. An activation group will be created if one with a matching name doesn't already exist in the job, otherwise the called program or service program will run in the existing activation group.

-----------------------------------
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.

==================================
MORE INFORMATION
==================================


Dig Deeper on Performance

Start the conversation

Send me notifications when other members comment.

Please create a username to comment.

-ADS BY GOOGLE

SearchDataCenter

Close