Learn the technique that enables the operating system programs to achieve this task.

In IBM i and its ancestors, an active job at the operating system level has an associated MI process, which is identified by a Process Control Space (PCS) MI object. The system pointer to a PCS object (with MI type/subtype code hex 1AEF) is used as the operand that identifies an MI process in process management MI instructions—for example, the Materialize Process Attributes (MATPRATR) instruction. Several other process-related MI instructions also expect a PCS pointer as an operand (or part of an operand) that identifies an MI process—for example, the Materialize Process Locks (MATPRLK) instruction, and the Transfer Object Lock (XFRLOCK) instruction. Thus, to use these MI instructions we need to first obtain a system pointer to the PCS object associated with an MI process.

This article introduces an effective method (locate the Work Control Block Table (WCBT) Entry of an active job in the WCBT via the job index and then retrieve the PCS pointer in the WCBTE) by investigating how the operating system programs achieve this task step by step.

A Brief Review of the Work Control Block Table (WCBT) and the Job Index

Leif Svalgaard discusses the Work Control Block Table (WCBT) and the Job Index in detail in chapter 9, The Work Control Block Table, of his great e-book, AS/400 Machine Level Programming. The technique discussed in this article is also covered in this chapter.

At the operating-system level, a job exists from the time it enters the system until it still has spooled output. Each existing job in the system has an entry in the WCBT. The WCBT actually consists of a master (or root) WCBT (QSYS/QWCBT00) and one or more WCBTs named QWCBT01, QWCBT02, and so on. A WCBT object is a space object with MI object type/subtype code hex 19D0. The master WCBT contains pointers to the other WCBTs, which actually contain WCBTEs allocated for jobs in the system. Entries in the WCBT are each hex 400 bytes long. For an active job, the system pointer to the PCS object associated with an MI process is at offset hex 20 in the WCBTE allocated for the job.

At offset hex 220 within the associated space of QWCBT00 is a system pointer to an index object, QSYS/QWCBT_JOB_INDEX, which will be referred to as the job index in the remaining portion of this article. The MI type/subtype code of the job index is hex 0EA4. The argument length (entry length) of the job index is 48 bytes; the key length of the job index is 32 bytes. The 32-byte key portion of the job index entry has two formats as shown in the following table.

The remaining 16 bytes of a job index entry represent a space pointer addressing the WCBTE of the corresponding job in the WCBT. Each job has two index entries in the job index, with index key format 1 and 2, respectively; the space pointers in these index entries address the same WCBTE. Note that two index key formats provide more flexibility for searching a specific job or multiple jobs within the job index. With index key format 1, you can search for a job or jobs by:

• Job name
• Job name and user name
• Job name, user name, and job number

With index key format 2, you can search for a job or jobs by:

• User name
• User name and job number
• User name, job number, and job name

Also note that the WCBT and the job index are all in the system domain.

The QWCCDSUC Program

Program QSYS/QWCCDSUC is the Command Processing Program (CPP) of the Work with User Jobs (WRKUSRJOB) command and is also the operating system program we are going to study in this article. To start, we need to perform the following two steps:

1. Complete a *SVL LIC trace upon a WRKUSRJOB command.
2. Dump the RISC instruction stream of the QWCCDSUC Program via the System Service Tools (SST).

The following are example commands to trace a WRKUSRJOB operation:

Next, we're going to investigate the process that the QWCCDSUC program uses to retrieve the system pointer to the PCS object associated with an MI process. We'll simulate this process with an OMI program (wcbt1.emi) and ILE RPG program (wcbt2.rpgle). Both these simulation programs accept a job name, a job user, and a job number to identify an active job in the system and return the PCS pointer of the job via their fourth parameter.

Retrieve the System Pointer to the Job Index

Debugging shows that during a WRKUSRJOB operation, the QWCCDSUC program retrieves the system pointer to the job index through the following steps:

1. 1.Locate the system pointer to the master WCBT (i.e., QWCBT00) stored in the Process Communication Object (PCO) of the current MI process at offset hex 1B0.
2. 2.Issue the Set Space Pointer from Pointer (SETSPPFP) MI instruction to retrieve the space pointer that addresses the associated space of QWCBT00.
3. 3.Locate the system pointer to the job index in the associated space of QWCBT00 at offset hex 220.

MI instructions in the QWCCDSUC program involved in this process and the PowerPC instructions generated for them (at V5R4) are listed below:

Notes

[1] The BLA form Branch (b) instruction branches the execution to address FFFFFFFFFF 801630, where the LIC routine pmgtpco_Gennaker in module #cfgrbla is located. The pmgtpco_Gennaker function returns the address of PCO of the current MI process via r3. Similar code is generated for a statement in an ILE program that invokes the Return PCO Pointer (PCOPTR2) system built-in or an MI instruction in an OMI program that refers to a data object or a space object (SPC) the addressability type of which is BASPCO (addressability type is based on PCO).

[2] The Load Quadword instruction reveals the offset value, hex 1B0, of the system pointer to the master WCBT (QWCBT00) in the PCO.

[3] At V5R4, code generated for a SETSPPFP MI instruction invokes the implementing LIC routine of SETSPPFP via a BLA 0X3801960 instruction. Here, the implementing LIC routine of SETSPPFP takes the system pointer to QWCBT00 as its source operand and returns the address of the associated space of QWCBT00 via r3.

[4] r1 always addresses the current Invocation Stack Frame (ISF). The Store Double (std) instruction stores the 8-byte address of the associated space of QWCBT00 in the ISF at offset hex 120. This reveals that the target operand of the SETSPPFP instruction is declared as a space pointer machine object (MSPPTR) in the source program of QWCCDSUC. The system pointer to the job index (QWCBT_JOB_INDEX) is stored at offset hex 220 in the associated space of QWCBT00.

In wcbt1.emi, the OMI instruction to simulate the MI instructions hex 01 and hex 40 in QWCCDSUC is the following:

The following are PowerPC instructions generated for the SETSPPFP instruction in our simulating program.

Similar ILE RPG source code in wcbt2.rpgle is the following:

Search the Job Index for a Specific Job

Debugging shows that during a WRKUSRJOB operation, the QWCCDSUC program retrieves the system pointer to the PCS object associated with a job through the following steps:

1. Search the job index for index entries of interests via a Find Independent Index Entry (FNDINXEN) MI instruction. At V5R4, the MI instruction number of this FNDINXEN instruction in the OPM program template of QWCCDSUC is hex 6BC. (The trace data of the *SVL LIC trace upon a WRKUSRJOB operation is handy to determine the location from which the FNDINXEN MI instruction is issued.)
2. Locate the WCBTE of a job via the space pointer in a returned index entry at offset hex 20.
3. Locate the PCS pointer of the job in the WCBTE at offset hex 20.

PowerPC instructions generated for MI instruction hex 6BC of QWCCDSUC:

[1] MI instruction hex 6BA of the QWCCDSUC program is a Copy Bytes with Pointers (CPYBWP) instruction that copies the address information in the space pointer machine object that addresses the associated space of QWCBT00 (like MSPPTR spp-root-wcbt@ in wcbt1.emi) to another space pointer. In the CPYBWP process, r21 is set to the address of the associated space of QWCBT00. Here, r4 addresses the system pointer to the job index stored in the associated space of QWCBT00 at offset 544 (hex 220).

Debugging shows that QWCCDSUC issues the FNDINXEN instruction with two search arguments in index key format 2 to retrieve all job index entries that begin with 1-byte constant '2' and a 10-byte user name. For example, the two 32-byte search arguments of a WRKUSRJOB LJL command might look like the following:

The following OMI source code (wcbt1.emi) simulates the FNDINXEN instruction in QWCCDSUC. Instead of searching for a range of job index entries, the code searches for a specific job index entry identified by fnd-arg.

Notes

[1] Once the job index is found, we can locate the PCS pointer (pcs@) at offset hex 20 in the WCBTE.

[2] Copy the PCS pointer in the WCBTE to parameter rtn-pcs@.

The ILE RPG source code (in wcbt2.rgple) that achieves the same task is as follows:

The complete source programs are available as wcbt1.emi and wcbt2.rpgle. Compile the WCBT1 and WCBT2 programs and change them to system state so that they can run at security level 40 or above.

Compile the following tiny test program (wcbt1b.rpgle).

Debug WCBT1B, set breakpoint at statement 19, and then call WCBT1B with parameters: the job name, job user, and job number of an active job. At breakpoint 19, issue the eval pcs@ debug command. The resulting display might look like the following:

You see that pcs@ is a system pointer to the PCS object (MI object type/subtype code is hex 1AEF) associated with an active job called 655110/LJL/TEA.

Final Thoughts

Now we've proven Leif's technique to retrieve the PCS pointer of an active job via the job index and WCBT by studying and simulating the operating system program QWCCDSUC. The WCBT1 (or WCBT2) program can be a useful utility. So what can we do with this utility? Think it over!

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.

Also Read

Advanced/Free - Function Calls and Return Values

PRACTICAL ILE - ILE Service Programs

Data-Manipulation Operations Using Free Format, Part Two