Three ways to associate a clean-up procedure to an entire application
Although a clean-up procedure can only be "connected" to a procedure, you can easily configure your application so that, for all intents and purposes, a clean-up procedure is associated with the whole application. Here are three ways to do it:
1. Register (i.e., associate) the clean-up procedure to the application's "main" procedure. Usually the "main" procedure is the first procedure called for the application or the one that controls the processing of the application (usually referred to as the entry-point procedure. or PEP).
2. Register clean-up procedures for any procedure that needs to perform clean-up. This is not technically a single clean-up procedure for the entire application. Instead, it is a way to ensure that every procedure in the application is properly cleaned-up in the event of an abnormal or unexpected end of the application.
3. Register (i.e., associate) a clean-up procedure for the application's activation group. If your application runs in its own activation group, you can associate a clean-up procedure with the activation group instead of a particular application procedure. When the activation group ends -- either normally or abnormally, for any reason including a job end (e.g., when a subsystem is ended) -- the system will call the clean-up procedure. You use the CEE4RAGE API (Register Activation Group Exit Procedure) to assign a clean-up procedure to an activation group. The API is very similar to the CEERTX API. Like the CEERTX API, CEE4RAGE accepts a procedure pointer to the clean-up procedure as its first parameter. There is no token parameter as there is with CEERTX, but there is a feedback parameter. CEE4RAGE assigns the clean-up procedure to the activation group in which the caller of the API is running.
For example: How to use the CEERTX API to establish a clean-up procedureThe code CLEANUP.RPG provides an example of a program registering a clean-up procedure. Since the design of a cleanup procedure depends entirely on the application, this clean-up procedure does not do any "cleaning-up." Instead, it displays the contents of the subfields of the TokenDS data structure to illustrate the use of the token parameter of the CEERTX API. When the clean-up procedure accesses the data in the TokenDS data structure, it is accessing the memory in the application procedure. Note that if the clean-up procedure is defined in the same source member -- as in this example -- it can access any files or other global items defined in the main procedure.
You can use this example as a starting point for designing your own clean-up procedures. You simply need to supply the details so it performs the clean-up duties appropriate to your application.
Remember that an application clean-up procedure (as opposed to an activation group clean-up procedure) is only called when the application ends abnormally. So, to see this example in action, you will need to run the program and end the job (from another job) when prompted. Then, you will see how the clean-up procedure gets control before the job ends.
The sample code also provides an example of using the CEE4RAGE API. Again, this example simply illustrates the mechanics of setting up a clean-up procedure for an activation group. You will need to fill in the actual clean-up details.
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 June 2006