04
Wed, Dec
6 New Articles

The Modify Addressability (MODADR) MI Instruction

RPG
Typography
  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

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 contexti.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:

 

> trcint *on trctbl(a) trctype(*svl)

   job(name-of-your-interactive-job) /* Start +

     a LIC trace against the current job */

> CALL PGM(QUSCRTUI)

   PARM('#0E0A#1   *CURLIB' /* Index name */

         'HELLO'

         'F'

         X'00000200'

         '1'

         X'00000010'

         '1'

         '1'

         *USE

        '')

> trcint *off trctbl(a) /* Stop trace and output the +

   trace records to spooled printer file QPCSMPRT. */

 

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:

 

MI SVL               IDENTIFIER : SV#00001                         TIME 14/05/23 12:23:23.605680   TDE# 0000000144E1

             CRTINX       INSTRUCTION #: E100   RETURN ADDRESS: 27386E1507 003BA0   PROGRAM NAME: QUSCRTUI

... ...

MI SVL               IDENTIFIER : SV#00001                         TIME 14/05/23 12:23:23.645568   TDE# 0000000144E1

             LOCK         INSTRUCTION #: E100   RETURN ADDRESS: 33779C2C5C 002904   PROGRAM NAME: QLIINSRT

... ...

MI SVL               IDENTIFIER : SV#00001                         TIME 14/05/23 12:23:23.645584   TDE# 0000000144E1

             MODADR       INSTRUCTION #: E100   RETURN ADDRESS: 33779C2C5C 00464C   PROGRAM NAME: QLIINSRT

 

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:

 

MI PROGRAM     SUBTYPE: 01     NAME: QLIINSRT ADDRESS: 33779C2C5C 000000

RISC INSTRUCTIONS (QLIINSRT)

     ADDRESS       LOCATION   OBJECT TEXT   SOURCE STATEMENT   MI INSTRUCTION NUMBERS

33779C2C5C 004638     0030B8   387C10C0     ADDI 3,28,4288         01D3

33779C2C5C 00463C     0030BC   EAFB0020     LD 23,0X20(27)

33779C2C5C 004640     0030C0   38970000     ADDI 4,23,0

33779C2C5C 004644     0030C4   39400065     ADDI 10,0,101

33779C2C5C 004648     0030C8   44000141     SCV 10

 

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.

 

/**

* @file mvad06.emi

*

* Modify the addressability of *DTAQ (0A01) TOM:

* - Transfer the addressability to TOM from LIBA to LIBB

* - Remove the addressability to TOM from LIBB

* - Insert the addressability to TOM back to LIBA

*

* @pre Create *DTAQ LIBA/TOM: CRTDTAQ LIBA/TOM MAXLEN(5)

*/

 

dcl sysptr liba@ auto init(

       "LIBA", type(ctx)

)                               ;

dcl sysptr libb@ auto init(

       "LIBB", type(ctx)

)                               ;

dcl sysptr tom@ auto init(

       "TOM", ctx("LIBA"), type(q)

)                               ;

dcl sysptr qcmd@ auto init(

       "QCMD", type(pgm)

)                               ;

 

       b       resolve         ;

move:   mats   libb@, tom@     ; /* MI inst 2: MODADR libb@, tom@ */

       callx   qcmd@, *, *    ;

       mats   tom@, tom@     ; /* MI inst 4: MODADR *, tom@ */

       callx   qcmd@, *, *     ;

       mats   liba@, tom@     ; /* MI inst 6: MODADR liba@, tom@ */

       callx   qcmd@, *, *     ;

       rtx     *               ;

resolve:

        rslvsp liba@, *, *, * ;

       rslvsp libb@, *, *, * ;

       rslvsp tom@, *, *, *   ;

       b       move           ;

pend                           ;

 

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.

 

MI PROGRAM                   SUBTYPE: 01     NAME: MVAD06     ADDRESS: 21E8836689 000000

RISC INSTRUCTIONS (MVAD06)

MI INSTRUCTION NUMBERS: 02 (address: 21E8836689 001648)

ADDRESS

OBJECT TEXT

(before)

SOURCE STATEMENT

OBJECT TEXT

(after)

SOURCE STATEMENT

Description

001648

E05FFFC2

LQ 2,0XFFC0(31),2

387FFFC0

addi 3,31,-64

r3 addresses system pointer libb@ in the Automatic Storage Frame (ASF)

00164C

7C0004C8

TXER 0,0,41

60000000

ori 0,0,0

No operation (noop)

001650

389B0000

ADDI 4,27,0

389B0000

ADDI 4,27,0

r4 addresses system pointer tom@ in ASF

001654

3940003D

ADDI 10,0,61

39400065

ADDI 10,0,101

Set r10 to the SCV 10 function number of MODADR

001658

44000141

SCV 10

44000141

SCV 10

Issue the MODADR MI instruction

MI INSTRUCTION NUMBERS: 04 (address: 21E8836689 001678)

001678

E05FFFD2

LQ 2,0XFFD0(31),2

E8608130

ld 3,0x8130(0)

Set op-1 of MODADR to null (8 bytes at address FFFFFFFFFF FF8130)

00167C

7C0004C8

TXER 0,0,41

60000000

ori 0,0,0

 

001680

389B0000

ADDI 4,27,0

389B0000

ADDI 4,27,0

 

001684

3940003D

ADDI 10,0,61

39400065

addi 10,0,101

 

001688

44000141

SCV 10

44000141

SCV 10

 

MI INSTRUCTION NUMBERS: 06 (address: 21E8836689 0016A8)

0016A8

E05FFFB2

LQ 2,0XFFB0(31),2

387FFFB0

addi 3,31,-80

r3 addresses system pointer liba@ in ASF

0016AC

7C0004C8

TXER 0,0,41

60000000

ori 0,0,0

 

0016B0

389B0000

ADDI 4,27,0

389B0000

ADDI 4,27,0

 

0016B4

3940003D

ADDI 10,0,61

39400065

ADDI 10,0,101

 

0016B8

44000141

SCV 10

44000141

SCV 10

 

 

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.

 

> crtdtaq liba/tom maxlen(5)

> call mvad06

> WRKOBJ *ALL/TOM *DTAQ /* The Work with Objects display might look like this */

Opt Object     Type     Library     Attribute   Text

     TOM         *DTAQ    LIBB                      

 

> WRKOBJ *ALL/TOM *DTAQ /* The Work with Objects display might look like this */

Opt Object     Type     Library     Attribute   Text

                                                      

(Cannot find object to match specified name.)      

 

> WRKOBJ *ALL/TOM *DTAQ /* The Work with Objects display might look like this */

Opt Object     Type     Library     Attribute   Text

     TOM         *DTAQ     LIBA                      

 

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

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

LATEST COMMENTS

Support MC Press Online

$

Book Reviews

Resource Center

  • SB Profound WC 5536 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. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More 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.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY 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.

  • SB HelpSystems ROBOT GenericForms 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.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA 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:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA 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.

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic 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.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra 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: