What can you do with it? Let's try some experiments and see.

In the EPA Headers section of chapter 8, Objects, of his famous book, Fortress Rochester, Dr. Frank Soltis mentions that there's an object-suspended state flag in the attribute byte (the first byte) of the Encapsulated Program Architecture (EPA) header of each MI object. As you might know, the attribute byte of an MI object's EPA header contains the most critical attributes of the MI object. So when should an MI object be suspended? By which operation or MI instruction can you suspend an MI object? And what can be done to a suspended MI object? If you're curious about the answers to these questions, read on.

Object Suspending

What is object-suspending? I wondered for a long time. In the documentation of the Retrieve Object Description (QUSROBJD) API in the IBM i Information Center, the description about the Storage field in the information returned for the OBJD0300 format is this:

Storage. The storage status of the object data. *FREE indicates the object data is freed and the object is suspended. *KEEP indicates the object data is not freed and the object is not suspended.

Similar information can be found in the description of the STG parameter of the Retrieve Object Description (RTVOBJD) command in the IBM i Information Center. Then if you take a glimpse at the online help information of the Freed item in a Display Object Description (DSPOBJD) display, you might come up with the answer to our question within a few seconds:

Freed. Indicates the storage status of the object data. Storage freed is not applicable for database files. Storage freed is not an attribute of a file, but is applicable only at the member level. The QUSRMBRD API can be used to determine if a member has its storage freed. Use format MBRD0200 to retrieve the member information. If the current number of records and the number of deleted records for the physical member both contain a -1 (negative one), then that member has had its storage freed.

YES

The storage for the object data has been freed. See the SAVOBJ or SAVLIB command, STG parameter, for more details.

NO

The storage for the object data has not been freed.

Both the above cited documentations are about the same thing—the storage status of an object (although using two different terminologies). This answers our question: A suspended object is an object whose storage is freed due to a SAVOBJ or SAVLIB command with the STG(*FREE) parameter.

According to Dr. Frank Soltis' Fortress Rochester book:

With a suspended object, only the headers of the object remain and the suspended bit in the EPA header is turned on.

So now let's start our first experiment to observe an MI object before and after its being suspended. Say MYPG is a program object. Apply the following operations on it:

1. 1.Issue a DSPOBJD MYPG *PGM DETAIL(*FULL) command and check the Storage information in the result display.
2. 2.Issue a DMPOBJ MYPG *PGM command and check the Single-Level Store (SLS) address of MYPG.
3. 3.Start an SST session, choose the Display/Alter storage function, and then record the attribute byte (the first byte) of the EPA header (EPA.ATT1) of MYPG and the sizes of the base segment of MYPG and its primary associated space. The size of a segment is indicated by the BIN(2) segment size field (in units of 512 bytes) at offset 2 from the beginning of a segment.
4. 4.Suspend program MYPG with a SAVOBJ STG(*FREE) command.
5. 5.Repeat steps 1 through 3.
6. 6.Compile and run an RPG program that calls program MYPG.
7. 7.Restore program MYPG from offline media (e.g., a save file to which MYPG is saved in step 4), check the attribute byte of the EPA header and object address of MYPG, and try to run it again.

The result of steps 1 through 5 is shown below:

From the output of steps 1 through 3 before and after the object being suspended, you may find out the following facts:

• Object-suspending does not change the SLS address of an MI object. This means suspending an MI object will not lead to the removal of the object or the creation of new objects.
• Segments composing an MI object and the associated space(s) are shrunk when the object is suspended. The MI object header and segment headers are reserved. The address of the MI object's base segment and the addresses of other segments in the MI object remain unchanged. In this experiment (done in VRM540), the base segment is shrunk to 8KB and the primary associated space is shrunk to 4KB.
• The suspended bit is bit-1 of the attribute byte (EPA.ATT1) of the EPA header of an MI object. The value of 1 in the suspended bit means the MI object is suspended.

Step 6 (calling the suspended program in an RPG program) will cause a hex 2203 Object suspended exception, aka MCH3403.

Step 7 (restoring the suspended program from offline media) will recover the suspended program to its normal state. EPA.ATT1 is recovered to its original value (hex 80). The SLS address of the recovered program remains unchanged. The restored program can be run normally. Now we know that a suspended MI object can be recovered via proper restore operations.

Who Suspends an MI Object?

Now you know that a SAVOBJ or SAVLIB command with parameter STG(*FREE) can suspend an object. So behind these commands, who actually implements the object-suspending work? An MI instruction supervisor linkage (*SVL) trace on a SAVxxx STG(*FREE) operation will show you the answer.

Start a *SVL trace via a Trace Internal (TRCINT) command, save the MYPG program again with a SAVOBJ STG(*FREE) command like the following, and then stop the trace and check the trace data:

In the collected *SVL trace data, you can find out the invocation to an MI instruction named SUSOBJ from program QSRFROBJ.

From Appendix E, SCV 10 Function Numbers, of Leif Svalgaard's great e-book AS/400 Machine Level Programming, we know that SUSOBJ is the Suspend Object MI instruction and the SCV 10 function number for SUSOBJ is 62. Now we are almost sure that the SUSOBJ MI instruction is the one that actually implements the object-suspending operation. To prove our assumption, we need to write a program to simulate the invocation of the SUSOBJ instruction made by the QSRFROBJ program at the RISC instruction level. Note that SUSOBJ is a blocked MI instruction; therefore, a user cannot compile a program that invokes the SUSOBJ instruction or its system built-in interface _SUSOBJ.

Dump the QSRFROBJ program via the "Dump to printer" function of the System Service Tools (SST) and locate the PowerPC instructions generated from the invocation of the SUSOBJ MI instruction in the RISC instruction stream in the resulting spooled file. The PowerPC instructions generated for the SUSOBJ MI instruction can be found before the RETURN ADDRESS (0E5D83A5DB 001E48) in the *SVL trace data shown above. At VRM540, these PowerPC instructions might look like the following:

From the above shown PowerPC instruction generated for the invocation of the SUSOBJ MI instruction, we know the following facts:

1. lThe SCV 10 function number is 62 (as documented in Leif's e-book).
2. lThe SUSOBJ MI instruction takes only one operand (via General Purpose Register (GPR) 3). By debugging the QSRFROBJ program, you determine that the only operand of SUSOBJ is a 16-byte system pointer addressing the MI object to suspend. Thus, to simulate the SUSOBJ instruction, a non-blocked MI instruction (implemented via SCV 10) that also takes a system pointer as its only operand would be a wonderful candidate, such as the Destroy Space (DESS) instruction or the Destroy Independent Index (DESINX).

The following OPM MI program susu.emi accepts the symbolic ID of an MI object, resolves the system pointer to the object, and then issues the DESS instruction upon the resolved system pointer.

Compile the OPM MI program via a wrapper utility of the Create Program (QPRCRTPG) API (e.g., mic) or simply call the QPRCRTPG API directly like so:

The PowerPC instructions generated for the fourth MI instruction (DESS OBJ@) in program SUSU are the following:

Before initiating the system call vectored to 10 (SCV 10), instruction ADDI 10,0,60 sets the value of GPR 10 to 60, which is the SCV 10 function number for DESS. Change the ADDI 10,0,60 instruction to ADDI 10,0,62 (62 is the SCV 10 function number for SUSOBJ) via the Display/Alter function of SST so that the actually MI instruction invoked within program SUSU is changed from DESS to SUSOBJ. The 4-byte encoded PowerPC instruction of ADDI 10,0,62 is hex 3940003E. Also remember to change the SUSU program to system state, since a blocked MI instruction SUSOBJ cannot be run under user state at security level 40 or above. Now we have an additional tool (the SUSU program) to help us with our further experiments.

What about a test of the newly developed object-suspending tool? For example, let's suspend a Data Area (*DTAARA) object and then restore it from a previous backup.

The Display Data Area display might look like the following:

With all the previously shown tests and experiments, we've proven that the Suspend Object (SUSOBJ) MI instruction suspends an MI object and it takes only one operand—a system pointer addressing the object to suspend. We've also seen that improper operations (e.g., calling a suspended program object or issuing a DSPDTAARA command on a suspended data area object) will cause a hex 2203, Object Suspended exception, aka MCH3403. Believe it or not, the documentation of the 2203 exception in the IBM i Information Center tells us a lot of extra information about the SUSOBJ instruction.

What Does the Documentation of the Object Suspended Exception Tell Us?

The Instructions Causing Exception section of the document of the Object Suspended exception in the IBM i Information Center reads:

Instructions that reference space, queue, index, byte string space, journal space, data space, or data space index objects, except for the following instructions:

- All Destroy instructions

- Lock Object (LOCK)

- Materialize Object Lock (MATOBJLK)

- Materialize Pointer (MATPTR)

- Materialize System Object (MATSOBJ)

- Resolve System Pointer (to the target object) (RSLVSP)

- Unlock Object (UNLOCK)

- Transfer Object Lock (XFRLOCK)

This piece of text reveals two aspects of important information about object-suspending:

• Which MI objects can be suspended? As indicated by the document, space, queue, index, byte string space, journal space, data space, or data space index objects can be suspended. Via our previously developed SUSU program, you may easily prove that program and module objects can also be suspended by the SUSOBJ instruction. Additionally, if you call the SUSU program to suspend a Data Queue (*DTAQ) object, you will receive the hex 2403 Pointer Addressing Invalid Object Type exception (aka MCH3603).
• Which MI instructions are allowed to be issued on a suspended MI object? For example, all suspended objects can be destroyed with a proper destroy MI instruction or a delete command. Additionally, you may try a Rename Object (RNMOBJ) or a Move Object (MOVOBJ) on a suspended object to see what would happen.

The Minimum Authorities Needed to Suspend an Object

In order to suspend an object, which minimum authorities to the object are needed? A simple experiment based on the Edit Object Authority (EDTOBJAUT) command and the previously developed SUSU program can achieve our goal. If interested, you may design such an experiment by yourself. My own experiment indicates that in order to suspend an object, the minimum authority to the object is the Object Control authority (at the MI level), i.e., the object existence (*OBJEXIST) authority mentioned in the CL and API documents.

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