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
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
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.Issue a DSPOBJD MYPG *PGM DETAIL(*FULL) command and check the Storage information in the result display.
- 2.Issue a DMPOBJ MYPG *PGM command and check the Single-Level Store (SLS) address of MYPG.
- 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.Suspend program MYPG with a SAVOBJ STG(*FREE) command.
- 5.Repeat steps 1 through 3.
- 6.Compile and run an RPG program that calls program MYPG.
- 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:
|
Before object being suspended |
After object being suspended |
Storage Information Returned by DSPOBJD |
Storage information: Size . . . . . . . . . . . . . . . . : 352256 Offline size . . . . . . . . . . . . : 0 Associated space size . . . . . . . : 4096 Optimum space alignment . . . . . . : YES Freed . . . . . . . . . . . . . . . : NO Compressed . . . . . . . . . . . . . : NO Object ASP number . . . . . . . . . : 1 Object overflowed . . . . . . . . : NO Object ASP device . . . . . . . . . : *SYSBAS Object ASP group . . . . . . . . . . : *SYSBAS |
Storage information: Size . . . . . . . . . . . . . . . . : 28672 Offline size . . . . . . . . . . . . : 352256 Associated space size . . . . . . . : 0 Freed . . . . . . . . . . . . . . . : YES Object ASP number . . . . . . . . . : 1 Object overflowed . . . . . . . . : NO Object ASP device . . . . . . . . . : *SYSBAS Object ASP group . . . . . . . . . . : *SYSBAS |
|
||
SLS Address of MYPG |
|
|
Attribute Byte in EPA Header (EPA.ATT1) |
hex 80 |
hex C0 |
Size of the Base Segment of MYPG (bytes) |
61440 |
8192 |
Size of the Associated Space of MYPG (bytes) |
8192 |
4096 |
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:
4 > TRCINT SET(*ON) TRCTBL(SVL) SIZE(1 *MB) TRCTYPE(*SVL) JOB(current-name-job) 4 > SAVOBJ MYPG LIB_NAME *SAVF SAVF(SAVF_NAME) STG(*FREE) 4 > TRCINT *OFF TRCTBL(SVL) OUTPUT(*PRINT) |
In the collected *SVL trace data, you can find out the invocation to an MI instruction named SUSOBJ from program QSRFROBJ.
MI SVL IDENTIFIER : SV#00001 TIME 14/01/24 18:14:19.232528 TDE# SUSOBJ INSTRUCTION #: 6300 RETURN ADDRESS: 0E5D |
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 (0E5D
MI PROGRAM SUBTYPE: 01 NAME: QSRFROBJ ADDRESS: 0E5D RISC INSTRUCTIONS (QSRFROBJ) ADDRESS LOCATION OBJECT TEXT SOURCE STATEMENT MI INSTRUCTION NUMBERS 0E5D 0E5D 0E5D 0E5D |
From the above shown PowerPC instruction generated for the invocation of the SUSOBJ MI instruction, we know the following facts:
- lThe SCV 10 function number is 62 (as documented in Leif's e-book).
- 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.
/** * @file susu.emi * * Suspend an MI object by object type code and object name */
DCL SPCPTR OBJ-T@ PARM ; DCL SPCPTR OBJ-NAME@ PARM ; DCL OL PL-MAIN ( OBJ-T@, OBJ-NAME@ ) PARM EXT ; ENTRY *(PL-MAIN) EXT ;
DCL DD OBJ-T CHAR(2) BAS(OBJ-T@) ; DCL DD OBJ-NAME CHAR(10) BAS(OBJ-NAME@) ; DCL SYSPTR OBJ@ AUTO ; DCL DD RSLV-TMPL CHAR(34) AUTO ; DCL DD * CHAR(2) DEF(RSLV-TMPL) POS(33) INIT(X'0000') ;
CPYBLA RSLV-TMPL(1:2), OBJ-T ; CPYBLAP RSLV-TMPL(3:30), OBJ-NAME, ' ' ; RSLVSP OBJ@, RSLV-TMPL, *, * ; BRK 'LOOK' ; DESS OBJ@ ; /* MI INST 4 */ RTX * ; PEND ; |
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:
CALL QPRCRTPG ( 'DCL SPCPTR OBJ-T@ PARM; DCL SPCPTR OBJ-NAME@ PARM; DCL OL PL-MAIN (OBJ-T@, OBJ-NAME@) PARM EXT; ENTRY *(PL-MAIN) EXT; DCL DD OBJ-T CHAR(2) BAS(OBJ-T@); DCL DD OBJ-NAME CHAR(10) BAS(OBJ-NAME@); DCL SYSPTR OBJ@ AUTO; DCL DD RSLV-TMPL CHAR(34) AUTO; DCL DD * CHAR(2) DEF(RSLV-TMPL) POS(33) INIT(X"0000"); CPYBLA RSLV-TMPL(1:2), OBJ-T; CPYBLAP RSLV-TMPL(3:30), OBJ-NAME, " "; RSLVSP OBJ@, RSLV-TMPL, *, *; BRK "LOOK"; DESS OBJ@; RTX *; PEND;' x'000001B8' 'SUSU *CURLIB ' 'Suspend object' 'QADBXRDBD QSYS ' 'SUSU ' '1010101000000' 'QSYSPRT QSYS ' x'00000001' '*CHANGE ' '*LIST *REPLACE ' x'00000002') |
The PowerPC instructions generated for the fourth MI instruction (DESS OBJ@) in program SUSU are the following:
MI PROGRAM SUBTYPE: 01 NAME: SUSU ADDRESS: 3E RISC INSTRUCTIONS (SUS) ADDRESS LOCATION OBJECT TEXT SOURCE STATEMENT MI INSTRUCTION NUMBERS 3E 3E 3E |
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.
4 > crtsavf savf File SAVF 4 > crtdtaara a01 *char value('Happy Spring Festival') Data area A01 created in library MYLIB. 4 > savobj a01 mylib *savf savf(savf 1 objects saved from library MYLIB. 4 > call susu (x' 4 > dspdtaara a01 Object A01 not referred to because saved with STG(*FREE) specified. Function check. MCH3403 unmonitored by QWCCDSVC at statement *N, instruction X'00EC'. 4 > rstobj a01 mylib *savf savf(savf 1 objects restored from MYLIB to MYLIB. 4 > dspdtaara a01 |
The Display Data Area display might look like the following:
Data area . . . . . . . : A01 Library . . . . . . . : MYLIB Type . . . . . . . . . : *CHAR Length . . . . . . . . : 21 Text . . . . . . . . . :
Value Offset *...+....1....+....2....+....3....+....4....+....5 0 'Happy Spring Festival' |
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
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
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.
LATEST COMMENTS
MC Press Online