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,
More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.
TRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now! Request Now.
Forms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.
Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:
Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.
IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn:
LATEST COMMENTS
MC Press Online