24
Mon, Jun
3 New Articles

Discover the Suspend Object (SUSOBJ) MI Instruction

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

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 thingthe 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:

 

 

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

19F4B7113C 000000

19F4B7113C 000000

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# 00000006F563

SUSOBJ       INSTRUCTION #: 6300   RETURN ADDRESS: 0E5D83A5DB 001E48   PROGRAM NAME: 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:

 

MI PROGRAM                   SUBTYPE: 01       NAME: QSRFROBJ   ADDRESS: 0E5D83A5DB 000000

RISC INSTRUCTIONS (QSRFROBJ)

     ADDRESS       LOCATION   OBJECT TEXT       SOURCE STATEMENT   MI INSTRUCTION NUMBERS

0E5D83A5DB 001E38       0008B8   38780020         ADDI 3,24,32       022

0E5D83A5DB 001E3C     0008BC     7FC3C088         TD 30,3,24

0E5D83A5DB 001E40       0008C0   3940003E         ADDI 10,0,62

0E5D83A5DB 001E44       0008C4   44000141         SCV 10

 

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.

 

/**

* @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: 3E2926447C 000000

RISC INSTRUCTIONS (SUS)

     ADDRESS       LOCATION   OBJECT TEXT       SOURCE STATEMENT   MI INSTRUCTION NUMBERS

3E2926447C 001684     000104     63830000         ORI 3,28,0                 04

3E2926447C 001688     000108     3940003C         ADDI 10,0,60

3E2926447C 00168C     00010C     44000141         SCV 10

 

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 savf190a

     File SAVF190A created in library MYLIB.

4 > crtdtaara a01 *char value('Happy Spring Festival')

     Data area A01 created in library MYLIB.

4 > savobj a01 mylib *savf savf(savf190a)

     1 objects saved from library MYLIB.

4 > call susu (x'190A' a01)

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(savf190a)

     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 operanda 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

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

$0.00 Raised:
$

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: