Let's experiment with the MODADR MI instruction and see what we discover.

In IBM i and its ancestors, a context (a library at the operating system level) is an MI object that contains addressabilities to other MI objects. An MI object either has its addressability placed in a context object (library) or not. If the addressability to an MI object is contained in a context, the MI object can be addressed symbolically via the Resolve System Pointer (RSLVSP) MI instruction through the context.

An MI object that is visible at the operating system level, which is referred to as an external object in IBM documentation, usually has its addressabilities contained in a context—i.e., a library. (IFS objects are an exception.) At the operating system level, we can move an external object from its containing library to another library via the Move Object (MOVOBJ) command or the Rename Object (QLIRNMO) API. As might be expected, an object-moving operation will definitely transfer the addressability to an MI object from its original containing context to its new containing context.

This article introduces the Modify Addressability (MODADR) MI instruction, which is responsible for modifying the addressabilities to MI objects contained in contexts. As a well-designed high-level machine interface, the MI instruction set of IBM i and its ancestors has changed (not dramatically) since System/38's announcement in 1978. As you might have known, the MODADR MI instruction has been around since System/38.

Briefly said, the MODADR instruction either inserts/removes the addressability to an MI object into/from a context, or transfers the addressability to an MI object from one context to another context. To understand the functionality and operands of the MODADR instruction, let's start by observing how this instruction is used by system-provided commands or APIs.

Investigate the MODADR MI Instruction

Experiments show that the MODADR instruction is involved in the following two kinds of operations:

• The moving of an object from one library to another library via the MOVOBJ command or the QLIRNMO API
• The create operations of many kinds of OS objects performed by corresponding Create commands (e.g., the Create Data Queue (CRTDTAQ) command) or Create APIs (e.g., the Create User Space (QUSCRTUS) API)

As you might know, the Create MI instructions, such as Create Space (CRTS) and Create Independent Index (CRTINX), allow the user to specify the context into which the addressability to the created MI object is inserted. However, the Create commands or Create APIs usually create an OS object without inserting its addressability into any context, and insert the addressability into the target context (i.e., library) via the MODADR instruction.

MI instruction supervisor linkage (*SVL) LIC traces on these two kinds of operations provide us enough information to figure out the operands of the MODADR instruction. The steps involved in the analyzing process are the following:

1. Complete a *SVL trace upon a Create or Move operation.

2. Find the trace record of the MODADR instruction in the collected trace records. Besides the MI instruction field, the trace record contains other two useful fields, the issuing program of the MI instruction and the return address field.

3. Dump the RISC instruction stream of the issuing program and locate the SCV 10 instruction generated for MODADR (the RISC instruction before the return address field in the trace record).

4. Analyze the RISC instructions generated for MODADR (including the SCV 10 instruction). By convention, addresses of operands of an MI instruction implemented via a SCV 10 instruction are passed to the LIC routine that actually implements the MI instruction via General Purpose Registers (GPRs) r3 through r6.

5. Debug the program that issues the MODADR instruction to determine the contents of each operand of MODADR.

For example, we can start our investigation of the MODADR instruction with a *SVL trace upon a Create User Index (QUSCRTUI) API, which creates a User Index object (with MI object type code/subtype code hex 0E0A) in an interactive job like so:

At V5R4M0, the trace record generated for the MODADR instruction and several other MI instructions of interest in the resulting spooled file might look like the following:

The trace records reveal the following:

1. At the time of creation (via the Create Index (CRTINX) MI instruction), the addressability to the index object is not inserted to a context.
2. Program QSYS/QLIINSRT issues the MODADR instruction to insert the addressability to the created index object into the context (i.e., library) specified in QUSCRTUI's first parameter, qualified user index name.
3. The exact location in the RISC instruction stream of QLIINSRT where the MODADR instruction is issued is one PowerPC instruction (4 bytes) before the RETURN ADDRESS field: 33779C2C5C 00464C. From the SST dump of the QLIINSRT program, we can find the disassembled PowerPC instructions generated for the MODADR instruction. For example, the following are the PowerPC instructions generated for MODADR (with MI instruction number hex 01D3) in the QLIINSRT program at V5R4M0:

The above PowerPC instructions generated for MODADR reveals the following:

1. The MODADR instruction is implemented via a SCV 10 (Supervisor Call Vectored (SCV) with dispatch code 10) instruction with SCV 10 function number 101 (at V5R4). Many thanks to Mark S. Waterbury who told me that the SCV 10 function numbers for MI instructions implemented via the SCV 10 instruction changed entirely at V6R1. Thus, if you are working on V6R1 or later releases, the SCV 10 function number of MDADR will be different from the above shown.
2. The MODADR instruction takes two operands. Addresses of operand 1 and operand 2 of MODADR are passed to MODADR's implementing LIC routine via GPR 3 and GPR 4, respectively. Debugging shows that operand 2 is an MI system pointer to the MI object whose addressability is to be changed, and operand 1 identifies the context object to receive the addressability of the MI object specified by operand 2.

At V5R4, I've seen two forms of operand 1 of MODADR. The QLIINSRT program invokes MODADR with operand 1 set to a space pointer addressing an instruction template whose format is the following (further details about this format are unknown):

• 16 bytes hex 00
• System pointer to the receiving context object
• 16 bytes hex 00

The QSYS/QLIMVOBJ program (the Command Processing Program (CPP) of the MOVOBJ command) uses the other form of operand 1 of MODADR—a system pointer to the receiving context object.

Simulate the MODADR Instruction

To fully understand the functionality of the MODADR instruction, we need to issue it from user programs. As a blocked MI instruction, it is impossible for us either to get a user program containing a MODADR instruction compiled or to issue the MODADR instruction (at runtime) from a user program at security level 40 or above. A workaround is to change the RISC instructions generated for a non-blocked MI instruction implemented via the SCV 10 PowerPC instruction in a user program to simulate the MODADR instruction and change the user program to system state.

In this section, I'd like to demonstrate an experiment that simulates the MODADR instruction to achieve the following operations:

• Transfer the addressability to Data Queue (*DTAQ) object TOM from context LIBA to context LIBB
• Remove the addressability to TOM from LIBB
• Insert the addressability to TOM back to LIBA

In the following tiny OMI source program (mvad06.emi), the non-blocked MI instruction Materialize Space (MATS) is used instead of MODADR to allow the OMI program to get compiled.

Compile the OMI program mvad06.emi via whatever wrapper utility of the Create Program (QPRCRTPG) API (e.g., mic). Modify the PowerPC Instructions generated for MI instruction 02, 04, and 06 like the following, so that at runtime the actual MI instructions being issued are the MODADR instructions.

Finally, change the program state field in the program header of MVAD06 from user state (hex 0001) to system state (hex 0080). At V5R4, the program state field is at offset hex 50 from the start of the program header.

Now let's test our modification. At each command entry prompted by the QCMD program, issue the WRKOBJ *ALL/TOM *DTAQ command to check where TOM is currently.

Document the MODADR Instruction

Trivial experimenting methods mentioned in the Rename (RENAME) MI Instruction article can be used to test the authorization and lock state required for each of the operands of the MODADR instruction. Now we are able to produce our version of documentation for the MODADR instruction.

Modify Addressability (MODADR)

Operand 1: System pointer, space pointer, or null

Operand 2: System pointer

Description: This instruction has the addressability to operand 2 inserted into a context, removed from a context, or transferred from one context to another. If operand 1 is a context object, the addressability to operand 2 is inserted into the context. If operand 2 is currently addressed by a context, this addressability is removed from the context. If operand 1 is null, the addressability to operand 2 is removed from the context that currently addresses it.

Authorization Required

Insert

                       Operand 1

Delete

                      Context currently addressing operand 1

Object management

                       Operand 2

Retrieve

                       Contexts referenced for address resolution

Lock Enforcement

Modify

Operand 1

Operand 2

Context currently addressing operand 1

Materialize

Contexts referenced for address resolution

Final Thoughts

The MODADR instruction and the RENAME instruction enable us to achieve hot swapping of software components since System/38. Consider the design of the QRPLOBJ library (for REPLACE(*YES) processing), which is a classic example of this technique.

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

The Importance of BIFs, BIF Essentials

Advanced/Free - Function Calls and Return Values

PRACTICAL ILE - ILE Service Programs