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,
Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. 
LATEST COMMENTS
MC Press Online