The solution revealed in this article allows you to start user-defined activation groups and run programs in them.
Have you seen an IBM i job containing more than 1000 activation groups? If not, you can call the following seven-line CL program (agp1001.clp) in an interactive job and then issue a DSPJOB OPTION(*ACTGRP) command to check what you get.
DCL VAR(&NUM) TYPE(*INT) LEN(4) VALUE(0) DCL VAR(&AGPMRK) TYPE(*CHAR) LEN(8) LOOP: IF COND(&NUM *GE 1001) THEN(GOTO CMDLBL(ENDLOOP)) CALL PGM(STRUAG) PARM(&AGPMRK) CHGVAR VAR(&NUM) VALUE(&NUM + 1) GOTO CMDLBL(LOOP) ENDLOOP: ENDPGM |
Limit on Activation Group Creation
Activation group (ACTGRP) is one of the most important features of the Integrated Language Environment (ILE) that was introduced to AS/400 at V2R3. All ILE programs and service programs are activated within an activation group. As a substructure of a job, an activation group contains the resources necessary to run the programs, such as static storage, heap storage, data management-related temporary resources (e.g., open data path (ODP), commitment control definitions, user interface manager (UIM) resources). For example, activation groups allow fine-grained resource management within a job, resource isolation within the same job, and the ability to use multiple commitment control definitions within a single job. If you're new to activation group-related ILE concepts, the ILE Concepts book is a good place to get started.
According to the Activation Group Creation section of chapter 3, ILE Advanced Concepts, of the ILE Concepts book: There is no Create Activation Group command. That's true. The only way you can create a new ILE activation group is to activate or call (implicitly activate) an ILE program or service program with the proper activation group attribute. The attribute is specified by using the ACTGRP parameter on the CRTPGM command or the CRTSRVPGM command at compile time. To create a named activation group (also referred to as user-named) with name MYACTGRP, you need to activate or call an ILE program that was previously created with the ACTGRP(MYACTGRP) parameter. To created a system-named activation group, you need to activate or call an ILE program that was previously created with the ACTGRP(*NEW) parameter. After the called program returns, the system-named activation group ends. Duplicate activation group names cannot exist within one job. Also note that activating a program (or service program) created with the ACTGRP(*CALLER) parameter will never lead to the creation of a new activation group. Instead, the *CALLER activation group attribute will cause the program to be activated in its caller's activation group. For detailed discussion about program activation and activation group attributes, please refer to the ILE Advanced Concepts chapter of the ILE Concepts book. The program activation operation is also discussed in detail in the documentation of the Call External (CALLX) MI instruction or the Transfer Control (XCTL) MI instruction.
As you've seen, runtime activation group creation depends on ILE programs created at compile time. So what if you need to create new activation groups independent of existing programs? Fortunately, there's an easy way to achieve that goal. This article discusses how to create a new activation group independent of existing programs, how to let an ILE program run in the created activation group, and how to end such an activation group. In this article, I'll refer to such an activation group as a user activation group.
Overview of the User Activation Group Solution
The user activation group solution allows you to start a user activation group (independent of any existing program), run programs in a started user activation group, and end a user activation group. The key technique—starting an activation group independent of any existing program—is quite straightforward. You need only activate a program object with a *NEW activation group attribute via either one of the Activate Bound Program APIs (QleActBndPgm or QleActBndPgmLong) or one of the Activate Bound Program (ACTBPGM) MI instructions (_ACTBPGM or _ACTBPGM2). The QleActBndPgm API and the _ACTBPGM system built-in use 4-byte activation group marks and activation marks, while the QleActBndPgmLong and the _ACTBPGM2 system built-in use 8-byte activation group marks and activation marks.
Components involved in the user activation group solution are the following:
- The keyed data queue (*DTAQ) object QTEMP/USRAGP—*DTAQ USRAGP is created the first time the STRUAG program is called in the current job. It serves as a table of activation group marks of all started user activation groups within the current job. The 8-byte key portion of a queue message in USRAGP is the activation group mark of a user activation group, and the 8-byte message text portion is the activation mark of service program (*SRVPGM) CALLX in the user activation group.
- The PGMNEW program—It is a do-nothing program with a *NEW activation group attribute. It's used by the STRUAG program to start new activation groups.
- The EOAG program—EOAG is used to end an activation group. Its activation group attribute is *CALLER. As you probably know, there are many methods to end an activation group directly or indirectly. EOAG invokes the high-level language end verb C library routine exit() to achieve that goal.
- The service program (*SRVPGM) CALLX—The activation group attribute of *SRVPGM CALLX is *CALLER, which means it can be activated in an existing activation group. The only export of CALLX is the callxx() procedure, which can be used to call any program with any parameter list. In this solution, *SRVPGM CALLX serves as a program-call agent. What's important is that the program call issued by procedure callxx() is initiated from the activation group into which we activated CALLX—a started user activation group.
- The STRUAG program—The STRUAG program is used to create a new user activation group (system-named activation group) by activating the PGMNEW program and returning the activation group mark it to its caller. When no parameter is passed, STRUAG reports the activation group mark interactively. Additionally, STRUAG activates *SRVPGM CALLX into the newly created activation group and then sends a queue message to the keyed data queue USRAGP with the key portion of the queue message set to the activation group mark and the message text portion of the queue message set to the activation mark of CALLX in the user activation group.
- The RUNINUAG program—The RUNINUAG program is used to run a program in a started user activation group. It accepts an activation group mark of a started user activation group, a qualified program name of the target program to run, and up to 253 parameters to pass to the target program. RUNINUAG searches *DTAQ USRAGP for the queue message of the user activation group by the input activation group mark, retrieves the activation mark of CALLX in the user activation group, which is then used to resolve the procedure pointer to the callxx() procedure exported by CALLX, and finally makes a program call to the target program via callxx().Note that to enable the called program to run in the started user activation group, the called program must be created with the *CALLER activation group attribute.
- The ENDUAG program—The ENDUAG program is responsible for ending a started user activation group. ENDUAG accepts an activation group mark of a started user activation group, runs the EOAG program (*CALLER) in the target user activation group to end it, and then removes the corresponding queue message from *DTAQ USRAGP.
Start a User Activation Group
The STRUAG program is expected to create a new user activation group within the current job and return the identifier (activation group mark) of the created user activation group to its caller. Tasks of STRUAG are the following:
- Start a new user activation group by activating PGMNEW whose activation groupattribute is *NEW
- Activate service program CALLX in the newly created user activation group
- Record the activation group mark and the activation mark of CALLX in the user activation group in data queue USRAGP
The source of the PGMNEW program (pgmnew.c) is the following:
void main(void) {} |
Make sure it's created with activation group attribute *NEW.
The STRUAG program optionally accepts one output parameter: the activation group mark of the newly started user activation group. If no parameter is passed, it will report the 8-byte activation group mark to the interactive user in hexadecimal format. The source code of the STRUAG program, struag.rpgle and struag_dq.clle, is the following:
struag_dq.clle
/** */ /** @file struap_dq.clle */ /** */ /** Create keyed *DTAQ QTEMP/USRAGP if it does NOT exit. */ /** */ PGM CHKOBJ OBJ(QTEMP/USRAGP) OBJTYPE(*DTAQ) MONMSG MSGID(CPF9801) EXEC(DO) CRTDTAQ DTAQ(QTEMP/USRAGP) + MAXLEN(8) SEQ(*KEYED) KEYLEN(8) ENDDO BYE: ENDPGM |
ILE CL module STRUAG_DQ is used to create the USRAGP data queue in the QTEMP library if it does not already exist.
struag.rpgle
/** * @file struag.rpgle * * Start a user activation group */
/copy mih-ptr /copy mih-pgmexec
/** * PEP Prototype of STRUAG */ d main_proc pr extpgm('STRUAG') d agp_mark 20u 0
* Prototype of CL module STRUAG_DQ d chk_dtaq pr extproc('STRUAG_DQ') * Prototype subprocedure rcd_agp d rcd_agp pr d agp_mark 20u 0 d actmk_callx 20u 0 * Prototype of C library routine cvthc() d cvthc pr extproc('cvthc') d 1a options(*varsize) d * value d 10u 0 value
d pgmnew s * d PGMNEW_NAME c 'PGMNEW' d CALLX_NAME c 'CALLX' d actdfn ds likeds(actbpgm_dfn2_t) d actspec ds likeds(actbpgm_pgm_spec2_t) d @actspec s * inz(%addr(actspec)) d hex_mark s 16a
d main_proc pi d agp_mark 20u 0
/free // [1] Start a new user ACTGRP // [1.1] Resolve system pointer to PGMNEW rslvsp_tmpl.obj_type = x'0201'; rslvsp_tmpl.obj_name = PGMNEW_NAME; rslvsp2(pgmnew : rslvsp_tmpl);
// [1.2] Start a new activation group by // activating ACTGRP(*NEW) program PGMNEW actdfn = *allx'00'; actbpgm2(actdfn : pgmnew);
// [2] Activate *SRVPGM CALLX into the newly // started user activation group actspec = *allx'00'; // [2.1] Resolve system pointer to *SRVPGM CALLX rslvsp_tmpl.obj_type = x'0203'; rslvsp_tmpl.obj_name = CALLX_NAME; rslvsp2(actspec.pgm : rslvsp_tmpl);
// [2.2] Activate *SRVPGM CALLX in the USRAGP actspec.tgt_agp = actdfn.agp_mark; actdfn = *allx'00'; actbpgm2(actdfn : @actspec);
// [3] Record agp-mark, act-mark of callx chk_dtaq(); rcd_agp( actdfn.agp_mark : actdfn.act_mark );
// [4] Set output agp-mark or report it to the user if %parms() > 0; agp_mark = actdfn.agp_mark; else; cvthc( hex_mark : %addr(actdfn.agp_mark) : 16 ); dsply 'Activation group mark (hex)' '' hex_mark; endif;
*inlr = *on; /end-free
/** * @func rcd_agp * Record the AGP mark and the activation mark of * *SRVPGM CALLX in *DTAQ QTEMP/USRAGP. */ p rcd_agp b d do_enq pr extpgm('QSNDDTAQ') d q_name 10a d q_lib 10a d msg_len 5p 0 d msg 20u 0 d key_len 3p 0 d key 20u 0
d DTAQ_NAME s 10a inz('USRAGP') d DTAQ_LIB s 10a inz('QTEMP') d msg_len s 5p 0 inz(8) d key_len s 3p 0 inz(8)
d rcd_agp pi d agp_mark 20u 0 d actmk_callx 20u 0 /free // Enqueue a message to *DTAQ QTEMP/USRAGP // Key=AGP mark // Message=Activation mark of *SRVPGM CALLX do_enq( DTAQ_NAME : DTAQ_LIB : msg_len : actmk_callx : key_len : agp_mark ); /end-free p e |
Compile struag_dq.clle and struag.rpgle into module objects and then create the STRUAG program with the activation group attribute set to a named activation group—for example, CRTPGM PGM(STRUAG) MODULE(STRUAG STRUAG_DQ) ACTGRP(QILE).
Call STRUAG to start a new user activation group in an interactive job. The output might look like the following:
4 > call struag DSPLY Activation group mark (hex) 000000000000001C |
To check all the user activation groups that have been started by STRUAG, you can check the queue messages within the QTEMP/USRAGP data queue by issuing either a Dump Object (DMPOBJ) command or a Display Queue Message (DSPQMSG) command.
The following is an example output of a DMPOBJ QTEMP/USRAGP *DTAQ command:
QUEUE MESSAGES- . 00001- .ENQUEUE DATE- 13/05/09 ENQUEUE TIME- 10:35:13 .KEY- 000000 00000000 0000001A .MESSAGE- 000000 00000000 0000158C . 00002- .ENQUEUE DATE- 13/05/09 ENQUEUE TIME- 10:40:14 .KEY- 000000 00000000 0000001C .MESSAGE- 000000 00000000 000021C8 . 00003- ... ... |
Note that the key portion of a queue message in the USRAGP data queue is the activation group mark of a user activation group, and the message text portion is the activation mark of the CALLX service program activated into the user activation group.
Run an ILE Program in a User Activation Group
An activation group is a static resource container that cannot run by itself. You must run at least one program in it. The RUNINUAG program is used to run a program in a started user activation group. It accepts an activation group mark of a started user activation group, the qualified program name of the target program (callee program) to run, and up to 253 parameters to pass to the callee program. The key to making RUNINUAG capable of running the callee program in a started user activation group is the program-call agent (*SRVPGM CALLX) that was previously activated in the user activation group by the STRUAG program. The invocation to the callee program is actually initiated by the callxx() procedure from the target user activation group in which CALLX is activated. Therefore, provided that the callee program's activation group attribute is *CALLER, it will run in the target user activation group.
The source code of *SRVPGM CALLX (callx.c) is the following:
/** * @file callx.c * * Exports: * - callxx() */
# include <stdlib.h> # include <string.h>
# pragma linkage(_CALLPGMV, builtin) void _CALLPGMV(void**, void**, unsigned);
/** * Call whoever! */ void callxx(void **pgm, void **argv, unsigned argc) { _CALLPGMV(pgm, argv, argc); } |
The callxx() procedure is the only export of *SRVPGM CALLX. Procedure callxx() accepts a system pointer to the callee program (passed by reference), an array of space pointer to individual arguments (passed by reference), and the number of arguments (passed by value), and then invokes the callee program via the Call Program with Variable Length Argument List (CALLPGMV) MI instruction.
Make sure the CALLX service program is created with the *CALLER activation group attribute—for example, CRTSRVPGM ... EXPORT(*ALL) ACTGRP(*CALLER).
The source code of the RUNINUAG program (runinuag.rpgle) is the following:
/** * @file runinuag.rpgle * * Run a program in a user activation group */
/copy mih-ptr /copy mih-pgmexec /copy mih-undoc
d objname_t ds qualified d obj 10a d lib 10a
/** * Prototype of RUNINUAG */ d main_proc pr extpgm('RUNINUAG') d agp_mark 20u 0 d pgm likeds(objname_t) * Up to 253 parameters to the callee program d 1a * ... ...
d main_proc pi d agp_mark 20u 0 d pgm likeds(objname_t) d x001 1a d x002 1a * ... ... d x253 1a
d get_callx_mark pr 20u 0 d agp_mark 20u 0 value d resolve_callxx pr * procptr d act_mark 20u 0 value
d LIBL c '*LIBL' d LIB_QTEMP c 'QTEMP' d ctx s * d callx_mark s 20u 0 d plist_ptr s * d plist ds likeds(npm_plist_t) d based(plist_ptr) d parm_desc_list ds likeds(parm_desc_list_t) d based(@parm_desc_list) d argc s 10u 0 d argv s * dim(253) d based(@argv) d i s 10u 0 d @arg s * d arg s 8a based(@arg) d callxx s * procptr d callee s * d callxx_proc pr extproc(callxx) d pgm_ptr * d argv * dim(1) options(*varsize) d argc 10u 0 value
/free // [1] Dequeue act-mark of *srvpgm CALLX by agp-mark callx_mark = get_callx_mark(agp_mark); if callx_mark = 0; // Failed to find target UAG // Error handling *inlr = *on; return; endif;
// [2] Resolve PROCPTR to proceture callxx() callxx = resolve_callxx(callx_mark); if callxx = *NULL; // Error handling *inlr = *on; return; endif;
// [3] Resolve a SYP to callee program monitor; if pgm.lib = LIBL; rslvsp_tmpl.obj_type = x'0201'; rslvsp_tmpl.obj_name = pgm.obj; rslvsp2(callee : rslvsp_tmpl); else; if pgm.lib = LIB_QTEMP; ctx = qtempptr(); else; rslvsp_tmpl.obj_type = x'0401'; rslvsp_tmpl.obj_name = pgm.lib; rslvsp2(ctx : rslvsp_tmpl); endif; rslvsp_tmpl.obj_type = x'0201'; rslvsp_tmpl.obj_name = pgm.obj; rslvsp4(callee : rslvsp_tmpl : ctx); endif; on-error; // Error handling *inlr = *on; return; endmon;
// [4] Compose argument list to pass to callee plist_ptr = npm_plist(); @parm_desc_list = plist.parm_desc_list; argc = parm_desc_list.argc - 2; @argv = %addr(plist.argvs) + 32; // for i = 1 to argc; // @arg = argv(i); // dsply i '' arg; // endfor;
// [5] Call callee via CALLXX callxx_proc( callee : argv : argc );
*inlr = *on; /end-free
/** * Return the activation mark of *SRVPGM CALLX in * the target activation group. * @remark 0 is returned if target UAG is NOT found. */ p get_callx_mark b d do_deq pr extpgm('QRCVDTAQ') d q_name 10a d q_lib 10a d msg_len 5p 0 d msg 20u 0 d timeout 5p 0 d key_order 2a d key_len 3p 0 d key 20u 0 d sender_len 3p 0 d sender_info 1a d rmv_flag 10a d rcv_len 5p 0 d deq_ec 8a
d DTAQ_NAME s 10a inz('USRAGP') d DTAQ_LIB s 10a inz('QTEMP') d msg_len s 5p 0 inz(8) d key_len s 3p 0 inz(8) * Do NOT wait! d timeout s 5p 0 inz(0) d key_order s 2a inz('EQ') d sender_len s 3p 0 inz(0) d sender_info s 1a * Do NOT remove queue message d rmv_flag s 10a inz('*NO') d rcv_len s 5p 0 inz(8) d deq_ec s 8a inz(x'0000000800000000')
d act_mark s 20u 0
d get_callx_mark pi 20u 0 d agp_mark 20u 0 value
/free do_deq( DTAQ_NAME : DTAQ_LIB : msg_len : act_mark : timeout : key_order : key_len : agp_mark : sender_len : sender_info : rmv_flag : rcv_len : deq_ec ); if msg_len = 0; // No such UAG! act_mark = 0; endif;
return act_mark; /end-free p e
/** * Resolve a procedure pointer to callxx() which * is exported by *SRVPGM CALLX. */ p resolve_callxx b d QleGetExpLong pr extproc('QleGetExpLong') d act_mark 20u 0 d exp_id 10i 0 d exp_name_len 10i 0 d exp_name 1a options(*varsize) * Pointer addressing the returned export d exp_ptr * procptr * Export type. 0=Not found, 1=procedure, 2=data d exp_type 10i 0 d ec 8a
d exp_id s 10i 0 inz(1) d exp_name_len s 10i 0 inz(0) d exp_name s 1a d exp_ptr s * procptr d exp_type s 10i 0 inz(0) d ec s 8a inz(x'0000000800000000')
d resolve_callxx pi * procptr d act_mark 20u 0 value
/free QleGetExpLong( act_mark : exp_id : exp_name_len : exp_name : exp_ptr : exp_type : ec ); if exp_type = 0; return *null; endif;
return exp_ptr; /end-free p e |
Notes
[1] Dequeue (without removing) the activation mark of *SRVPGM CALLX in the target user activation group via the activation group mark (retrieving a queue message whose message key is equal to the activation group mark of the target user activation group).
[2] Resolve a procedure pointer to procedure callxx() via the QleGetExpLong API by using the activation mark of CALLX in the target user activation group and the export identifier of callxx(). The export identifier of callxx() is 1, since it's the only export of *SRVPGM CALLX.
[3] Resolve a system pointer to the callee program by using the input qualified program name.
[4] Prepare the argument list to pass to the callee program. The NPM Procedure Parameter List Address (_NPMPARMLISTADDR) system built-in is used to retrieve the address of the parameter list passed to the main procedure of the RUNINAUG program. The ILE RPG prototype of _NPMPARMLISTADDR and related data structures are defined in mih-pgmexec.rpgleinc. As you know, parameters passed by reference to a program are by conversion. For this reason, the argument area (plist.argvs) contains an array of space pointers to individual parameters. Offset 32 bytes to skip the first two parameters of STRUAG from the beginning of plist.argvs; you get the array of space pointers to individual arguments to pass to the callee program, argv. The number of arguments to pass to the callee program can be calculated by subtracting 2 from the number of parameters passed to the STRUAG program, argc = parm_desc_list.argc - 2.
[5] Call the callee program via the resolved procedure pointer to callxx(), passing to the callee program the resolved system pointer, the argument list, and the number of arguments.
End a User Activation Group
The ENDUAG program allows you to end a started user activation group. ENDUAG accepts an activation group mark of the user activation group to end, runs the EOAG program (*CALLER) in the target user activation group to end it, and then removes the corresponding queue message from *DTAQ USRAGP.
The EOAG program ends the activation group in which it's running by invoking one of the high-level language end verbs, the C library routine exit(). The source of the EOAG program (eoag.c) is the following:
# include <stdlib.h> void main() { exit(0); } |
The source of the ENDUAG program (enduag.rpgle) is the following:
/** * @file enduag.rpgle * * End a user activation group */
/copy mih-ptr /copy mih-pgmexec
/** * Prototype of ENDUAG */ d main_proc pr extpgm('ENDUAG') d agp_mark 20u 0
d main_proc pi d agp_mark 20u 0
d get_callx_mark pr 20u 0 d agp_mark 20u 0 value d remove n value d resolve_callxx pr * procptr d act_mark 20u 0 value
d callx_mark s 20u 0 d argc s 10u 0 inz(0) d argv s * dim(1) d callxx s * procptr d callee s * d EOAG_PGM c 'EOAG' d callxx_proc pr extproc(callxx) d pgm_ptr * d argv * dim(1) options(*varsize) d argc 10u 0 value
/free // [1] Dequeue act-mark of *srvpgm CALLX by agp-mark callx_mark = get_callx_mark(agp_mark : *off); if callx_mark = 0; // Failed to find target UAG // Error handling *inlr = *on; return; endif;
// [2] Resolve PROCPTR to proceture callxx callxx = resolve_callxx(callx_mark); if callxx = *NULL; // Error handling *inlr = *on; return; endif;
// [3] Resolve a SYP to the EOAG program rslvsp_tmpl.obj_type = x'0201'; rslvsp_tmpl.obj_name = EOAG_PGM; rslvsp2(callee : rslvsp_tmpl);
// [4] Call EOAG via CALLXX callxx_proc( callee : argv : argc );
// [5] Remove UAG entry from *DTAQ USRAGP get_callx_mark(agp_mark : *on);
*inlr = *on; /end-free
/** * Return the activation mark of *SRVPGM CALLX in * the target activation group. * @remark 0 is returned if target UAG is NOT found. */ p get_callx_mark b d do_deq pr extpgm('QRCVDTAQ') d q_name 10a d q_lib 10a d msg_len 5p 0 d msg 20u 0 d timeout 5p 0 d key_order 2a d key_len 3p 0 d key 20u 0 d sender_len 3p 0 d sender_info 1a d rmv_flag 10a d rcv_len 5p 0 d deq_ec 8a
d DTAQ_NAME s 10a inz('USRAGP') d DTAQ_LIB s 10a inz('QTEMP') d msg_len s 5p 0 inz(8) d key_len s 3p 0 inz(8) * Do NOT wait! d timeout s 5p 0 inz(0) d key_order s 2a inz('EQ') d sender_len s 3p 0 inz(0) d sender_info s 1a * Do NOT remove queue message d rmv_flag s 10a inz('*NO') d rcv_len s 5p 0 inz(8) d deq_ec s 8a inz(x'0000000800000000')
d act_mark s 20u 0
d get_callx_mark pi 20u 0 d agp_mark 20u 0 value d remove n value
/free if remove; // Remove queue message? rmv_flag = '*YES'; endif;
do_deq( DTAQ_NAME : DTAQ_LIB : msg_len : act_mark : timeout : key_order : key_len : agp_mark : sender_len : sender_info : rmv_flag : rcv_len : deq_ec ); if msg_len = 0; // No such UAG! act_mark = 0; endif;
return act_mark; /end-free p e
/** * Resolve a procedure pointer to callxx() which * is exported by *SRVPGM CALLX. */ p resolve_callxx b d QleGetExpLong pr extproc('QleGetExpLong') d act_mark 20u 0 d exp_id 10i 0 d exp_name_len 10i 0 d exp_name 1a options(*varsize) * Pointer addressing the returned export d exp_ptr * procptr * Export type. 0=Not found, 1=procedure, 2=data d exp_type 10i 0 d ec 8a
d exp_id s 10i 0 inz(1) d exp_name_len s 10i 0 inz(0) d exp_name s 1a d exp_ptr s * procptr d exp_type s 10i 0 inz(0) d ec s 8a inz(x'0000000800000000')
d resolve_callxx pi * procptr d act_mark 20u 0 value
/free QleGetExpLong( act_mark : exp_id : exp_name_len : exp_name : exp_ptr : exp_type : ec ); if exp_type = 0; return *null; endif;
return exp_ptr; /end-free p e |
Notes
[1] Dequeue (without removing) the activation mark of *SRVPGM CALLX in the target user activation group via the activation group mark (retrieving a queue message whose message key is equal to the activation group mark of the target user activation group).
[2] Resolve a procedure pointer to procedure callxx().
[3] Resolve a system pointer to the EOAG program.
[4] Call the EOAG program to end the target user activation group.
[5] Remove the queue message of the target user activation group from *DTAQ USRAGP.
An Example of Using User Activation Groups
Here's a simple example of the user activation group that starts activation group-level commitment controls (CMTCTL) in user activation groups. The following is the source of an ILE CL program MYCMTCTL (mycmtctl.clle) that starts an activation group-level CMTCTL and sets the text description of the CMTCTL to its CHAR(20) parameter &DESC:
/** @file mycmtctl.clle */ /** Compile: */ /** - CRTCLMOD ... */ /** - CRTPGM ... ACTGRP(*CALLER) */ PGM PARM(&DESC) DCL VAR(&DESC) TYPE(*CHAR) LEN(20) STRCMTCTL LCKLVL(*CS) CMTSCOPE(*ACTGRP) TEXT(&DESC) |
Make sure program MYCMTCTL is created with the *CALLER activation group attribute.
Call STRUAG twice to start two user activation groups amd then run MYCMTCTL in each user activation group to start activation group-level commitment control:
4 > call struag DSPLY Activation group mark (hex) 000000000000001C ? *N DSPLY Activation group mark (hex) 000000000000001C ? *N 4 > call struag DSPLY Activation group mark (hex) 000000000000001D ? *N DSPLY Activation group mark (hex) 000000000000001D ? *N 4 > call runinuag (x'000000000000001C' 'MYCMTCTL *LIBL' 'Spring') 4 > call runinuag (x'000000000000001D' 'MYCMTCTL *LIBL' 'Summer') |
Now issue a DSPJOB OPTION(*CMTCTL) command. The output might look like this:
Commitment Opt Definition Text _ 28 Spring _ 29 Summer |
Final Thoughts
While activation groups are an amazing feature of ILE RPG, they also bring additional complexities. A notable example is that, in a multi-threaded job, ending an activation group from a secondary thread will lead to the end of the job. For example, if a program with activation group attribute *NEW is called accidentally in a secondary thread of a multi-threaded job, at the return of the program, the system-named activation group (created due to the invocation of the program) ends, which in turn leads to the end of the multi-threaded job. In my opinion, an IBM i developer needs a sound understanding of the working mechanisms of activation groups before deciding to manage runtime resources at the activation group level.
Also, please keep in mind that, as a construct that manages resources, an activation group itself also consumes storage. Consider the AGP1001 program shown at the beginning of this article for example; issuing the WRKDSKSTS command before and after calling AGP1001, respectively, shows that the 1,001 activation groups consume about half a gigabyte of storage.
LATEST COMMENTS
MC Press Online