MC Press Online

Thursday, Apr 27th

Last updateThu, 27 Apr 2017 1pm

You are here: Home ARTICLES Programming RPG Sometimes Programs and Procedures Want to Know: Who Am I?

Programming / RPG

Sometimes Programs and Procedures Want to Know: Who Am I?

SUPPORT MC PRESS - VISIT OUR SPONSORS

NEW BOOK!

IBM i Security Administration and Compliance


ORDER YOUR COPY

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

Click for this Month's

Bookstore Special Deals

If you were a program, could you answer this question?

 

In software programming, sometimes a program, a procedure, or a process or thread needs to answer the question: "Who am I?" For example, in an error-logging framework, after getting the answer to this question, the error-logging framework might write a log entry like the following: "Failed to allocate heap storage in SOMELIB/SOMEPGM, procedure FOO of module BAR. From job QZDASOINITQUSER      123456, thread 00000030." To answer the "Who am I?" question, programmers could hard-code names of programs or procedures everywhere log entries need to be written, but doing that is obviously error-prone and will make code hard to maintain. A utility that can answer this question on behalf of any program or procedure will significantly reduce the efforts in maintaining code that writes log entries.

 

Here, I'll introduce a high-performance implementation of such a utility in i5/OS. The approach discussed here was implemented as an ILE RPG procedure called who_am_i. The basic goals are the following:

  • To retrieve information about the program or procedure currently being called—including program, library, module, procedure, and statement information—who_am_i first retrieves the suspend point of its caller via MI instruction Materialize Invocation Attributes (MATINVAT) with option 24 and then retrieves detailed information about its caller's invocation by applying MI instruction Materialize Pointer Information (MATPTRIF) on the suspend pointer. A suspend pointer is a type of MI pointer that identifies a suspend point or a resume point. A suspend point is a location within an invocation's routine where execution was suspended due to a call, an interruption, or a machine operation. A resume point is a location within an invocation's routine where execution will resume if execution is allowed to resume in the invocation.
  • To retrieve the job ID of the current job, who_am_i first materializes the system pointer to the current job's process control space (PCS) object by MI instruction Materialize Process Attributes (MATPRATR) with option hex 25 and then materializes the name of the PCS object via MI instruction Materialize Pointer (MATPTR). An i5/OS job can be uniquely identified by a PCS object; the name of a PCS object is also the job ID of the corresponding job.
  • To retrieve the thread ID of the current thread, who_am_i uses MI instruction Retrieve Thread Identifier (RETTHID), which returns an 8-byte thread ID of the current thread that uniquely identifies a thread within a job.

Retrieving Information About the Program or Procedure Currently Being Called

who_am_i first retrieves the suspend point of its calling procedure via MI instruction Materialize Invocation Attributes (MATINVAT) with option 24 and then retrieves detailed information about its caller by applying MI instruction Materialize Pointer Information (MATPTRIF) on the suspend pointer to the suspend point of who_am_i's caller.

 

The following ILE RPG prototypes of the system built-ins of these two instructions and declarations of related data structures are extracted from mih52.rpgleinc.

 

     /* Materialization template of MATINVAT. */

     d matinvat_tmpl_t...

     d                 ds                  qualified

 

     /* Materialization template of MATINVAT when a pointer is returned. */

     d matinvat_ptr_t...

     d                 ds                  qualified

     d     ptr                         *

 

     /* Invocation identification structure for MATINVAT. */

     d invocation_id_t...

     d                 ds                  qualified

     d     src_inv_offset...

     d                               10i 0

     d     org_inv_offset...

     d                               10i 0

     d     inv_range                 10i 0

     d                                4a

     d     inv_ptr                     *

     d                               16a

 

     /* _MATINVAT2 (Materialize Invocation Attributes (MATINVAT)) */

     d matinvat2       pr                  extproc('_MATINVAT2')

     d     receiver                        likeds(matinvat_tmpl_t)

     d     invocation_id...

     d                                     likeds(invocation_id_t)

     d     selection                       likeds(matinvat_selection_t)

 

     /* _MATINVAT (Materialize Invocation Attributes (MATINVAT)) */

     d matinvat        pr                  extproc('_MATINVAT1')

     d     receiver                        likeds(matinvat_tmpl_t)

     d     selection                       likeds(matinvat_selection_t)

 

     /* Materialization template for MATPTRIF. */

     d matptrif_tmpl_t...

     d                 ds                  qualified

 

     /**

      * Materialization template for MATPTRIF when materializing a

      * suspend pointer.

      */

     d matptrif_susptr_tmpl_t...

     d                 ds                  qualified

     d                                     based(dummy_ptr)

     d     bytes_in                  10i 0

     d     bytes_out                 10i 0

     d                                7a

      *

      * Pointer type.

      * hex 01 = System pointer

      * hex 02 = Space pointer

      * hex 03 = Suspend pointer

      *

     d     ptr_type                   1a

     d                                1a

      *

      * Program type.

      * hex 00 = Non-bound program

      * hex 01 = Bound program

      * hex 02 = Bound service program

      * hex 04 = Java program

      *

     d     pgm_type                   1a

     d     pgm_ccsid                  5u 0

     d     pgm_name                  30a

     d     pgm_ctx                   30a

     d                                4a

      * Module information

     d     mod_name                  30a

     d     mod_qual                  30a

     d                                4a

      * Procedure information

     d     proc_dict_id...

     d                               10i 0

     d     proc_name_length_in...   

     d                               10i 0

     d     proc_name_length_out...   

     d                               10i 0

     d     proc_name_ptr...

     d                                 *

     d                                8a

      * Statement information

     d     stmt_ids_in...

     d                               10i 0

     d     stmt_ids_out...   

     d                               10i 0

     d     stmt_ids_ptr...

     d                                 *

 

     /* _MATPTRIF (Materialize Pointer Information (MATPTRIF)) */

     d matptrif        pr                  extproc('_MATPTRIF')

     d     receiver                        likeds(matptrif_tmpl_t)

     d     ptr                         *

     d     selection                  4a

 

Notes:

  • The MATINVAT instruction has two system built-ins: _MATINVAT1 materializes attributes of the current invocation, and _MATINVAT2 materializes attributes of an invocation in the current thread's call stack identified by the invocation_id operand. To materialize the suspend pointer to the suspend point in an invocation, set the value of the attr_id field of the selection operand of MATINVAT to 24.
  • The src_inv_offset field of MATINVAT's invocation_id operand indicates the offset of the target invocation relative to the invocation located by the source invocation pointer, the inv_ptr field of the invocation_id operand. A null value of the inv_ptr field indicates that the source invocation is the current invocation. For example, specifying -1 for the src_inv_offset field and a null value for the inv_ptr field of invocation_id operand means that attributes of the invocation of the current invocation's caller are to be materialized.
  • When materializing a suspend pointer via instruction MATPTRIF, some bits of the 4-byte selection operand indicate whether or not a specific type of information is returned. For example, if bit 1 of selection is set, the program type information will be returned in the pgm_type field of the materialization template for MATPTRIF.

 

The following piece of code was used in the who_am_i procedure to retrieve the detail attributes of its caller.

 

      /copy mih52

     d inv_id          ds                  likeds(invocation_id_t)

     d susptr          ds                  likeds(matinvat_ptr_t)

     d sel             ds                  likeds(matinvat_selection_t)

     d ptrd            ds                  likeds(matptrif_susptr_tmpl_t)

     d mask            s              4a

      /free

           // materialize suspend pointer of target invocation

           inv_id = *allx'00';

           inv_id.src_inv_offset = -1;  // caller's invocation

           sel = *allx'00';      // clear attribute selection template for MATINVAT

           sel.num_attr   = 1;

           sel.attr_id    = 24;  // materialize suspend pointer

           sel.rcv_length = 16;

           matinvat2( susptr

                    : inv_id

                    : sel );

 

           // materialize suspend ptr

           ptrd = *allx'00';

           ptrd.bytes_in = %size(ptrd);

           ptrd.proc_name_length_in = proc_name.len;

           ptrd.proc_name_ptr = %addr(proc_name.name);

           ptrd.stmt_ids_in = stmts.num;

           ptrd.stmt_ids_ptr = %addr(stmts.stmt);

           mask = x'5B280000';  // binary value: 01011011,00101000,00000000,00000000

             // bit 1 = 1, materialize program type

             // bit 3 = 1, materialize program context

             // bit 4 = 1, materialize program name

             // bit 6 = 1, materialize module name

             // bit 7 = 1, materialize module qualifier

             // bit 10 = 1, materialize procedure name

             // bit 12 = 1, materialize statement id list

           matptrif( ptrd : susptr.ptr : mask );

      /end-free

 

When MATPTRIF returns successfully, attributes of who_am_i's caller's invocation will be returned in the following fields of structure ptrd:

  • pgm_type—Type of the calling program. For an OPM program, an ILE program, an ILE service program, or a Java program, the value of pgm_type would be hex 00, 01, 03, or 04, respectively.
  • pgm_ctx—Name of the library where the calling program resides.
  • pgm_name—Name of the calling program.
  • mod_name—Name of the module to which the calling procedure belongs.
  • mod_qual— Name of the module qualifier. This is the qualifier specified during program creation to identify where this module was found when the bound program (ILE program or ILE service program) was created. The module qualifier is used to differentiate between two different modules of the same name. This field usually contains a library name.
  • proc_name_length_out—The length of the returned name of the calling procedure.
  • proc_name_ptr—The name of the calling procedure is returned at the storage location pointed to by this space pointer. Note that proc_name_ptr is an input field, and the user is responsible for allocating storage pointed to by proc_name_ptr.
  • stmt_ids_out—The number of statement IDs returned.
  • stmt_ids_ptr—A statement ID list is returned at the storage location pointed to by this space pointer. Note that stmt_ids_ptr is an input field, and the user is responsible for allocating storage it points to.

Retrieving the Job ID of the Current Job

Since an i5/OS job is uniquely identified by a process control space (PCS) object, and the name of a PCS object is also the job ID of the corresponding job, who_am_i first materializes the system pointer to the current job's PCS pointer via the MATPRATR instruction with option hex 25 and then materializes the name of the PCS object via the MATPTR instruction.

 

The following ILE RPG prototypes of the system built-ins of these two instructions and declarations of related data structures are extracted from mih52.rpgleinc.

 

     /**

      * Materialization template for MATPRATR when a pointer attribute

      * is materialized.

      */

     d matpratr_ptr_tmpl_t...

     d                 ds                  qualified

     d     bytes_in                  10i 0

     d     bytes_out                 10i 0

     d                                8a

     d     ptr                         *

 

     /* _MATPRATR1 (Materialize Process Attributes) */

     d matpratr1       pr                  extproc('_MATPRATR1')

     d     receiver                        likeds(matpratr_tmpl_t)

     d     option                     1a

 

     /* _MATPRATR2 (Materialize Process Attributes) */

     d matpratr2       pr                  extproc('_MATPRATR2')

     d     receiver                        likeds(matpratr_tmpl_t)

     d     pcs                         *

     d     option                     1a

 

     /* Materialization template for MATPTR */

     d matptr_tmpl_t   ds                  qualified

     d     bytes_in                  10i 0

     d     bytes_out                 10i 0

     d     ptr_type                   1a 

 

     /* Materialization template for MATPTR when materializing a SYSPTR */

     d matptr_sysptr_info_t...

     d                 ds                  qualified

     d     bytes_in                  10i 0

     d     bytes_out                 10i 0

     d     ptr_type                   1a 

     d     ctx_type                   2a 

     d     ctx_name                  30a 

     d     obj_type                   2a 

     d     obj_name                  30a 

     d     ptr_auth                   2a 

     d     ptr_target                 2a 

 

     /* _MATPTR (Materialize Pointer (MATPTR)) */

     d matptr          pr                  extproc('_MATPTR')

     d     receiver                        likeds(matptr_tmpl_t)

     d     ptr                         *

 

Note that _MATPRATR1 materializes attributes of the current MI process (job), while _MATPRATR2 materializes attributes of an MI process identified by the pcs operand, which is a system pointer to a PCS object. The following code was used in procedure who_am_i to retrieve the job ID of the current job.

 

      /copy mih52

     d pcs_tmpl        ds                  likeds(matpratr_ptr_tmpl_t)

     d matpratr_opt    s              1a   inz(x'25')

     d syp_attr        ds                  likeds(matptr_sysptr_info_t)

 

      /free

           // retrieve the PCS pointer of the current MI process

           pcs_tmpl.bytes_in = %size(pcs_tmpl);

           matpratr1(pcs_tmpl : matpratr_opt);

 

           // retrieve the name of the PCS object, aka job ID

           syp_attr.bytes_in = %size(syp_attr);

           matptr(syp_attr : pcs_tmpl.ptr);

      /end-free

 

The returned job ID stored in field syp_attr.obj_name would look like the following: 'QTRXC00012QTCP      270659    '.

 

To test the performance of the above-mentioned technique, two test programs written in RPG, jobi.rpgle, and jobi2.rpgle, are available from open-source project i5/OS Programmer's Toolkit. jobi.rpgle uses the Retrieve Job Information (QUSRJOBI) API to retrieve the job ID of the current job in format of JOBI0100 100,000 times; jobi2.rpgle accomplishes the same work via the above-mentioned technique. The following is the result of running these two test programs on an i525 machine:

  • Time taken to retrieve job ID via the QUSRJOBI API 100,000 times is 784,000 microseconds.
  • Time taken to retrieve job ID via the combination of the MATPRATR instruction and the MATPTR instruction is 128,000 microseconds, about one sixth of the time used in the former test.

Retrieving the Thread ID of the Current Thread

In contrast with retrieving thread ID via Pthread API pthread_getthreadid_np or the combination of pthread_self and pthread_getunique_np, the RETTHID instruction is a more clean and efficient way to retrieve the unique thread ID within a job. Note that the 8-byte thread ID returned by RETTHID is also used by other MI instructions or Work Management APIs—for example, the Control Thread (QTHMCTLT) API. The lower 4 bytes of this 8-byte thread ID are also used by job-related CL commands to represent thread IDs within a job—for example, DSPJOB OPTION(*THREAD).

 

The following ILE RPG prototype of the system built-in RETTHID can be found in mih52.rpgleinc.

 

     /* RETTHID, retrieve thread identifier */

     d retthid         pr             8a   extproc('_RETTHID')

 

Put All the Parts Together

Now let's put all the parts together. The following is the prototype of procedure who_am_i and the declarations of data structures used by it. The implementation of who_am_i is omitted for clearness. For the latest version of procedure who_am_i, please refer to who.rpgle from open-source project i5/OS Programmer's Toolkit.

 

     /* Program information. */

     d pgm_info_t      ds                  qualified

     d     ctx                       30a

     d     name                      30a

 

     /* Module information. */

     d module_info_t   ds                  qualified

     d     name                      30a

     d     qualifier                 30a

 

     /* Procedure name. */

     d proc_name_t     ds                  qualified

     d                                     based(dummy_ptr)

     d     len                        5u 0

     d     name                   32767a

 

     /* Statement ID list. */

     d stmt_list_t     ds                  qualified

     d                                     based(dummy_ptr)

     d     num                        5u 0

     d     stmt                      10i 0 dim(1024)

 

     /* Job ID and thread ID. */

     d job_id_thread_id_t...

     d                 ds                  qualified

     d     jid                       30a

     d     tid                        8a

 

     /**

      * Who am I?

      *

      * @param [out] pgm_info, returned program info.

      * @param [out] mod_info, returned module info.

      * @param [out] proc_name, returned procedure name.

      * @param [out] stmst, returned statement ID list.

      * @param [out] MI process (job) id and thread id.

      * @param [in]  inv_offset, offset of target invocation.

      *              -1 if no passed, which means who_am_i()'s caller.

      *

      * @return 1-byte program type.

      *         hex 00 = Non-bound program

      *         hex 01 = Bound program

      *         hex 02 = Bound service program

      *         hex 04 = Java program

      *         hex FF = invalid input parameters

      */

     d who_am_i        pr             1a

     d     pgm_info                        likeds(pgm_info_t)

     d     mod_info                        likeds(module_info_t)

     d     proc_name                       likeds(proc_name_t)

     d     stmts                           likeds(stmt_list_t)

     d     job_thd_id                      likeds(job_id_thread_id_t)

     d                                     options(*nopass)

     d     inv_offset                10i 0 value options(*nopass)

 

who_am_i accepts four required output parameters that represent the returned program information, module information, procedure name, and statement IDs, respectively. The fifth parameter of who_am_i, job_thd_id, is an optional output parameter; if specified, who_am_i will fill it with the job ID and thread ID of the current thread. The sixth parameter, inv_offset, is an optional input parameter that indicates the offset of the target invocation relative to who_am_i. Only zero or negative values are allowed for inv_offset; the default value is -1, which indicates the caller of who_am_i. Decrease the value of inv_offset to indicate earlier invocations in the call stack; for example, a value of -2 for inv_offset means the caller of the caller of who_am_i. The return value of who_am_i is a 1-byte field that indicates the program model of the calling program.

 

Now, let's write a test program for procedure who_am_i.

 

     /*

      * Include prototype of who_am_i() and declarations of DSs used by it.

      * ... ...

      */

 

     /* Prototype of MI library function cvthc() */

     d cvthc           pr                  extproc('cvthc')

     d     receiver                    *   value

     d     source                      *   value

     d     length                    10i 0 value

 

     d pgm_info        ds                  likeds(pgm_info_t)

     d mod_info        ds                  likeds(module_info_t)

     d proc_name       ds                  likeds(proc_name_t)

     d                                     based(proc_name_ptr)

     d proc_name_ptr   s               *

     d stmts           ds                  likeds(stmt_list_t)

     d                                     based(stmts_ptr)

     d stmts_ptr       s               *

     d thread          ds                  likeds(job_id_thread_id_t)

     d pgm_type        s              1a

     d msg             s             30a

 

      /free

 

           proc_name_ptr = %alloc(2 + 128);

           proc_name.len = 128;

 

           stmts_ptr = %alloc(2 + 4 * 4); // for up to 4 statement ids

           stmts.num = 4;

 

           pgm_type = who_am_i( pgm_info

                              : mod_info

                              : proc_name

                              : stmts

                              : thread );

 

           // check returned information

           // program info

           msg = %trim(%subst(pgm_info.ctx : 1 : 10)) + '/'

                 + %subst(pgm_info.name : 1 : 10);

           dsply 'Program:     ' '' msg;

 

           // Module information, procedure name, and statement ID

           // are meaningless for an OPM program.

           if pgm_type > x'00';

               // module info

               msg = %trim(%subst(mod_info.qualifier : 1 : 10)) + '/'

                     + %subst(mod_info.name : 1 : 10);

               dsply 'Module:      ' '' msg;

 

               // procedure name

               msg = %subst(proc_name.name : 1 : proc_name.len);

               dsply 'Procedure:   ' '' msg;

 

               // first statement ID in stmt id list

               dsply 'Statement ID:' '' stmts.stmt(1);

           endif;

 

           // job id and thread id

           dsply 'Job ID:      ' '' thread.jid;

           // thread.tid

           cvthc(%addr(msg) : %addr(thread.tid) : 16);

           dsply 'Thread ID:   ' '' msg;

 

           dealloc proc_name_ptr;

           dealloc stmts_ptr;

           *inlr = *on;

      /end-free

 

Build your test RPG module and bind it into a program object along with the module that exports who_am_i. Call your test program; the output might look like the following:

 

DSPLY  Program:         QGPL/TESTWHO

DSPLY  Module:          QGPL/WHO

DSPLY  Procedure:       TESTWHO

DSPLY  Statement ID:           108

DSPLY  Job ID:          TEA       HENRY     270803

DSPLY  Thread ID:       00000000000000BA

 

Now you have a high-performance utility that can answer the "Who am I?" question on behalf of any program or procedure.

 

There is also an OPM MI program whoami.emi, which follows the same rationale of procedure who_am_i and sends materialized information as informational messages to its caller's call message queue. For example, call program WHOAMI from the command line of the main menu, and you will get the following output:

 

3>> call whoami

    Program     QUICMD

    Library     QSYS

 

 

as/400, os/400, iseries, system i, i5/os, ibm i, power systems, 6.1, 7.1, V7,

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