MC Press Online

Saturday, Jun 24th

Last updateFri, 23 Jun 2017 1pm

You are here: Home ARTICLES Programming RPG 1001 Activation Groups Within a Single Job

Programming / RPG

1001 Activation Groups Within a Single Job

Support MC Press - Visit Our Sponsors

NEW BOOK!

Evolve Your RPG Coding: Move from OPM to ILE ... and Beyond


ORDER YOUR COPY

*******************

Click for this Month's

Bookstore Special Deals

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 techniquestarting an activation group independent of any existing programis 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 programIt 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 programEOAG 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) CALLXThe 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 CALLXa started user activation group.
  • The STRUAG programThe 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 programThe 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 programThe 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 groupfor 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 attributefor 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.

 

Junlei Li

Junlei Li is a programmer from Tianjin, China, with 10 years of experience in software design and programming. Junlei Li began programming under i5/OS (formerly known as AS/400, iSeries) in late 2005. He is familiar with most programming languages available on i5/OS—from special-purpose languages such as OPM/ILE RPG to CL to general-purpose languages such as C, C++, Java; from strong-typed languages to script languages such as QShell and REXX. One of his favorite programming languages on i5/OS is machine interface (MI) instructions, through which one can discover some of the internal behaviors of i5/OS and some of the highlights of i5/OS in terms of operating system design.

 

Junlei Li's Web site is http://i5toolkit.sourceforge.net/, where his open-source project i5/OS Programmer's Toolkit (https://sourceforge.net/projects/i5toolkit/) is documented.

BLOG COMMENTS POWERED BY DISQUS