Do you know all the kinds of pointers and understand what they do?

In i5/OS, machine interface (MI) pointers are used to represent many things:

• Objects and the data within objects
• Run-time primitives, such as program or procedure invocation
• Suspend point and resume point in an invocation
• Procedures of a module object
• Locations within an OPM program or a procedure of an ILE module object that the control flow can be branched to
• And so on

Like data types defined in a programming language different types of MI pointers are the primitive data types that we use to work with the MI instruction set.

For example, when using MI instruction Materialize System Object (MATSOBJ) to retrieve the attributes of an MI object, we should pass a system pointer addressing the MI object as the second operand and pass a space pointer addressing the receiver buffer allocated for the returned MI object attributes.

According to IBM's document "Machine Interface Architecture Introduction", the following types of MI pointers exist. This table is a brief overview. Details about each type follow after the table.

*An 8-byte procedure pointer refers to an active procedure through teraspace. Since the teraspace address space is private to an MI process, a teraspace procedure pointer is referred to as a process-local procedure pointer. There are two types of teraspace pointers: 8-byte space pointers and 8-byte procedure pointers. Teraspace pointers are not discussed in this article.

**MI pointers are strong-typed; a non-typed pointer exists only from the programming language point of view. You can declare a pointer as non-typed, and once it becomes valid, it always has a definitive pointer type.

Figure 1: This is the common layout of 16-byte MI pointers.

There's a common layout of the different types of 16-byte MI pointers:

• The first byte of the 16-byte MI pointer value, byte 0, stores the type of an MI pointer.
• Bytes 1-7 store pointer type-specific information.
• Bytes 8-15 store the virtual address portion of a system pointer, a space pointer, or a data pointer. Note that this address is a single-level storage address in the 64-bit virtual address space of i5/OS. This virtual address remains unchanged during the life of an MI object. An 8-byte virtual address is composed with a 5-byte segment identifier and a 3-byte segment offset for a big segment (a 16MB segment) or is composed with a 6-byte segment identifier and a 2-byte segment offset for a small segment (a 64KB segment).

To materialize the attribute of an MI pointer, use the MI instruction Materialize Pointer (MATPTR).

System Pointer

A system pointer identifies an MI object and always addresses the base segment of an MI object. A system pointer is the only way that an MI object can be referred to. Figure 1 shows the binary layout of a system pointer to program object QSYS/QDBPUT, which is extracted from the dump result of space object QSYS/QINSEPT.

Note: Space object QSYS/QINSEPT is also referred to as the System Entry Point Table (SEPT), where resolved system pointers to OPM APIs are stored. Since a space pointer to the SEPT is also available in the Process Communication Object (PCO) of each MI process (i5/OS job), to dump the content of the SEPT, you can use the CL command DMPSYSOBJ in either of following forms:

• DMPSYSOBJ OBJ(QINSEPT) CONTEXT(QSYS)
• DMPSYSOBJ OBJ(*PCS) OFFSET(0)

Figure 2: This is the layout of SYSPTR to *PGM QSYS/QDBPUT. (Click image to enlarge.)

This is the binary format of the system pointer to QSYS/QDBPUT:

• Byte 0—MI pointer type—For a system pointer, it is always hex 00.
• Byte 1—For a program object, it is set to the value of the 'BRING SIZE' attribute in its program header.
• Byte 2—Additional pointer authorities to those are set in byte 15.
• Bytes 3-7—Not used.
• Bytes 8-12 or 8-13—Segment identifier of an MI object's base segment. (See note below.)
• Bytes 14—MI object type code. An MI object is addressed by its base segment identifier. The low-order two bytes of a system pointer are not used to store the segment offset value of the virtual address. Byte 14 of a system pointer stores the object type code of an MI object: for example, hex 02 for a program object, hex 0A for a queue object, hex 0E for an index object, etc. For a complete list of all valid MI object type codes, refer to IBM's documentation on MI instruction Resolve System Pointer (RSLVSP).
• Byte 15—Pointer authorities set into a system pointer by system state programs or SLIC code. Nine types of authorities can be set into a system pointer (object control, object management, authorized pointer, space authority, retrieve, insert, delete, update, execute). Nine bits are needed to hold all the nine pointer authorities. Byte 2 of a system pointer holds pointer authorities together with byte 15.

Note: A system pointer always addresses the base segment (the first segment) of an MI object. The MI object header of an MI object is stored at the beginning of an MI object's base segment. The MI object header consists of the following two parts:

• The segment header of the base segment of an MI object, which contains important attributes of the MI object and base segment itself, such as segment type, size of the base segment, object domain (system domain or user domain), virtual address of the base segment, virtual address of an MI object's associated space.
• The Encapsulated Program Architecture (EPA) header, which contains attributes of an MI object, such as existence attribute; damage status of an MI object; name, type code, and subtype code of an MI object; attributes of an MI object's associated space (space attributes, space initial value, size of associated space); public authorities for the MI object; owner's authorities for the MI object; virtual address of owner's user profile object; virtual address of the MI object; and virtual address of the context object through which the MI object can be addressed.

For example, from the MI object header of data queue object Q1 shown in Figure 3, we can see that the object existence attribute of Q1 is permanent (ATT1 attribute in the EPA header is set to hex 80), object domain of Q1 is system domain (DOMAIN attribute in the segment header is set to hex 8000), the virtual address of the associated space of Q1 is 335F7912E5 000020 (SPACE attribute in the segment header), size of the base segment is 4096 bytes (SIZE attribute of the segment header, in 512 bytes), size of the associated space of Q1 is hex 0FE0 (SPSZ attribute in the EPA header), and so on.

Figure 3: MI object headers reveal much information about data queue objects. (Click image to enlarge.)

Using System Pointers to Manipulate MI Objects

When an MI object's address is resolved by MI instruction RSLVSP or when an MI object is created successfully, a valid system pointer is returned. The returned system pointer can be used in further manipulation of the MI object addressing by the system pointer. There are primarily five categories of MI instructions that manipulate MI objects:

• Instructions that create a specific type of MI object— Their names always start with "CRT," such as Create Space (CRTS) or Create Independent Index (CRTINX).
• Instructions that destroy a specific type of MI object— Their names always start with "DES," such as Destroy Space (DESS) or Destroy Independent Index (DESINX).
• Instructions that retrieve attributes of an MI object—Their names always start with "MAT." For example, Materialize Space Attributes (MATS) retrieves the space-object-specific attributes of a space object, while Materialize System Object (MATSOBJ) retrieves the common attributes of an MI object.
• Instructions that modify the attributes of particular type of MI object—Their names always start with "MOD." For example, the Modify Space Attributes (MODS) instruction modifies the attributes of a space object.
• Instructions that operate a particular type of MI object—For example, Enqueue (ENQ) enqueues a queue message to a queue object (with object type code hex 0A). Materialize Queue Messages (MATQMSG) retrieves one or more messages on a queue object. Insert Independent Index Entry (INSINXEN) inserts one or more index entries into an independent index object (with object type code 0E). Activate Program (ACTPG) creates an activation entry in one of the activation groups of an MI process (i5/OS job) for an OPM program and returns a space pointer to the static storage frame of the program if the OPM program uses static storage. (See also Appendix B below, "Example of Using MI Instruction Activate Program (ACTPG)").

An MI object can be created as either permanent or temporary. This is referred to as the existence attribute of an MI object. According to IBM's documentation on MI instruction Test Temporary Object (TESTTOBJ), a temporary object does not persist across IPLs and is automatically destroyed at system termination. Additionally, a temporary object is not owned by any user profile, and the addressability of a temporary object is not inserted into a context object when it is created.

A permanent MI object can be addressed through either a context object or the machine context. The following MI object types can be addressed only through the machine context:

• User profile (with object type code hex 08)
• Logical unit description (with object type code hex 10)
• Network description (with object type code hex 11)
• Controller description (with object type code hex 12)
• Class of service description (with object type code hex 14)
• Mode description (with object type code hex 15)
• Network interface description (with object type code hex 16)
• Connection list (with object type code hex 17)
• Auxiliary server (with object type code hex 1D)

When a permanent MI object is created (addressed through a context object), the addressability of the object is inserted in the context object. When a permanent MI object is destroyed, its addressability is removed from the context object. The context attribute in an MI object's EPA header indicates the current context object through which the MI object can be addressed.

The creation or deletion of a permanent MI object also affects the user profile of the owner of the MI object. Each time an MI object's ownership is assigned to or revoked from a user profile, the Change Date/Time attribute of the user profile object changes correspondingly. MI instruction Materialize User Profile (MATUP) can be used to retrieve the number of MI objects owned by a specific user profile. A permanent MI object cannot be destroyed automatically and must be explicitly destroyed using an appropriate destroy instruction according to the object type of the MI object.

The materialize instructions are the only interface through which a user program above the MI layer can access the attributes of an existing MI object. For a particular type of MI objects, a materialize instruction is defined to retrieve attributes of that type of MI object. For example, Materialize Independent Index Attributes (MATINXAT) retrieves the attributes of an index object. Additionally, Materialize System Object (MATSOBJ) retrieves common attributes of an MI object, such as object state attributes (suspended status, damage status, existence attribute, and so on), object name, object size, creation/modification time, attributes of an MI object's associated space, etc.

The modify instructions are the only interface through which a user program above the MI layer can modify the attributes of an MI object. For a particular type of MI objects, a modify instruction is defined to modify attributes of that type of MI object. For example, Modify Independent Index (MODINX) modifies the attributes of an index object. Modify Space Attributes (MODS) modifies the attributes of a space object or the associated space of an MI object.

Example ILE RPG program T057 (below) manipulates an independent index object (object type code of an index object is hex 0E). Examples of the above-mentioned five categories of instructions that manipulate MI objects are covered in this program. They are:

• Create Independent Index (CRTINX)
• Destroy Independent Index (DESINX)
• Find Independent Index Entry (FNDINXEN)
• Insert Independent Index Entry (INSINXEN)
• Materialize Independent Index Attributes (MATINXAT)
• Modify Independent Index (MODINX)
• Remove Independent Index Entry (RMVINXEN)

For ILE RPG prototypes of these MI instructions, please refer to Appendix A below, "ILE RPG Prototype of Independent Index Management Instructions."

Note: According to IBM's document on user index objects (with external object type *USRIDX) Using User Index APIs, a user index is an object that allows search functions for data in the index and automatically sorts data based on the value of the data. User indexes are permanent objects in the user domain or in the system domain. They have an object type of *USRIDX and a maximum size of 1 terabyte (1,099,511,627,776 bytes). They help streamline table searching, cross-referencing, and ordering of data. In general, if your table is longer than 1000 entries, an index performs faster than a user-sorted table. You can use user indexes to:

• Provide search functions
• Do faster insert operations than in a database file
• Do faster retrieve operations than in a database file
• Create an index by name, such as a telephone directory
• Use order entry programs
• Look up abbreviations in an index
• Sort data automatically based on the hexadecimal value of a key

User index entries cannot contain a pointer. You can save and restore all the data in an index. You can also save and restore user indexes to another system.

Features mentioned in the IBM document are really those of all independent index objects. A user index is nothing but an index object that was created indirectly by the Create User Index (QUSCRTUI) API as a permanent index object with object type/subtype code hex 0E0A. The only interface to create an independent index at the MI level is instruction Create Independent Index (CRTINX). Additionally, when creating an index object with CRTINX, one important attribute bit in the index attribute byte of the creation template operand is the entry format attribute bit, which determines whether the created index object can contain only scalar data or both pointers and scalar data. When the entry format attribute bit is set to 1, entries of the created index object can contain pointers, such as system pointers or space pointers. This is an important feature of index objects when fast search functions for MI objects are needed. For example, the index object QSYS/QWCBT_JOB_INDEX (with object type/subtype code hex 0EA4) stores a snapshot of current jobs in the system. Each entry of QSYS/QWCBT_JOB_INDEX contains a job identifier and a space pointer containing the offset of the specific entry of that job in the Work Control Block Table (WCBT) space object QSYS/QWCBT01. (A WCBT entry in the WCBT space object contains the system pointers to the Process Control Space (PCS) object of a job, a job's job message queue object (QJOBMSGQ), a job's spool control block (QSPSCB), and so on.) Index object QSYS/QWCBT_JOB_INDEX is keyed by the job identifier field; therefore, the system can efficiently locate a specific job in the system by searching the QWCBT_JOB_INDEX index for the space pointer to a job's WCBT entry by job identifier.

The following ILE RPG code is extracted from t057.rpgle, which is provided by the open-source project i5/OS Programmer's Toolkit.

Code Notes:

(1) Allocate and initialize index description template and then create the target index object with the initialized index description template using instruction CRTINX. In this example, a temporary index object named NIHAO is to be created with object type/subtype code hex 0E01, without an associated space, with fixed index entries. Length of index entries is 32 bytes, including the 8-byte key value portion.

(2) Insert a couple of entries into index object NIHAO using instruction INSINXEN with key values 'OBJD0200' and 'OBJD0400', respectively.

(3) Search index object NIHAO using instruction FNDINXEN for an entry whose key value is equal to 'OBJD0200'.

(4) Remove index entry whose key value is equal to 'OBJD0200' from index object NIHAO using instruction RMVINXEN.

(5) Materialize index attributes of NIHAO using instruction MATINXAT. Note that after the above operations on index object NIHAO, the materialized operation statistics attributes should be Entries inserted = 2, Entries removed = 1, and Number of find operations = 1.

(6) Modify index object NIHAO's "immediate update" attribute to "No immediate update".

(7) Destroy index object NIHAO using instruction DESINX.

Space Pointers

A space pointer addresses bytes within a space object. It is the pointer type used in both MI and high-level languages (HLL) to address program storage, such as stack, static, and heap storage. There are two types of space pointers:

• Space pointers, aka space pointer data objects—Space pointer data objects are used heavily to represent data objects in HLLs, such as void * or char * in C, or * in ILE RPG.
• Machine space pointers (MSPPTR), aka space pointer machine objects—There's no way for ILE HLL programs to utilize a MSPPTR. In MI programs, a MSPPTR can be used in most cases where a space pointer data object is allowed, with the following limits:
• a MSPPTR cannot be passed as a parameter, be part of a structure (SPC), be based on a pointer, or be duplicated by MI instructions such as Copy Bytes with Pointers (CPYBWP). Also, a MSPPTR is logically only automatic (AUTO) in storage scope.

Different HLLs provide different space addressing support via space pointers. Space addressing support via space pointers in ILE RPG is discussed in the article "Use the MI to Work with Pointers in ILE RPG."

By using MI instruction Set Space Pointer from Pointer (SETSPPFP), you can address the associated space of an MI object. This instruction is especially useful when utilizing storage provided by space objects. The following example program T059 translates EBCDIC characters into ASCII characters by using the EBCDIC-to-ASCII translation table stored in space object ASCII. Space object ASCII contains the same content as table object QSYS/QASCII. A table object, with external object type *TBL, is a space object whose object type/subtype code is hex 1906. Table objects can be used to translate data or to specify an alternate collating sequence. The following is the source code of ILE RPG program T059, t059.rpgle. ILE RPG prototypes of MI instruction Resolve System Pointer (RSLVSP), Set Space Pointer from Pointer (SETSPPFP), and Translate Bytes (XLATEB) can be found in mih52.rpgleinc.

Code Notes:

(1) Resolve space object ASCII.

(2) Address the associated space of space object ASCII by using instruction SETSPPFP. The ILE RPG prototype of instruction SETSPPFP can be found in mih52.rpgleinc.

(3) Translate EBCDIC characters to ASCII characters according to the translation table stored in ASCII.

Call program T059, and you will get the following result:

Data Pointers

Data pointers are a special form of space pointer. In addition to storing the virtual address of a data object, a DTAPTR also stores data attributes (scalar data type and length) in its reserved bytes of its high-order 8 bytes. The following figure is the binary layout of the high-order 8-byte value of a data pointer representing a packed decimal (6, 2) scalar data object.

Figure 4: DTAPTR stores data attributes.

This is the binary layout of a data pointer:

Bits 0-3 of byte 0 are always set to hex C for a data pointer.

Bits 4-7 of byte 0 are scalar type represented by a data pointer:

• Hex 00, signed binary
• Hex 01, floating point
• Hex 02, zoned decimal
• Hex 03, packed decimal
• Hex 04, character
• Hex 06, ONLYNS
• Hex 07, ONLYS
• Hex 08, EITHER
• Hex 09, OPEN
• Hex 0A, unsigned binary

Bytes 4-5 are scalar length:

• If zoned decimal or packed decimal, byte 4 stores the number of fractional digits; byte 5 stores total number of digits.
• If binary, bytes 4-5 store a 2-byte binary of value 2, 4, or 8.
• If float, bytes 4-5 store a 2-byte binary of value 4 or 8.
• If character, bytes 4-5 store a 2-byte binary-length value in bytes.
• If ONLYNS, bytes 4-5 store a 2-byte binary-length value in number of double-byte characters.
• If ONLYS, bytes 4-5 store an even 2-byte binary-length value in bytes, including any SO and SI.
• If EITHER or OPEN, bytes 4-5 store a 2-byte binary-length value in bytes, including any SO and SI.

Note: Four data types are supported for data pointer definition of extended (double-byte) character fields: ONLYNS, ONLYS, EITHER, and OPEN. Except for ONLYNS, the double-byte character data must be surrounded by a shift out control character (SO = hex 0E) and a shift in control character (SI = hex 0F). The ONLYNS field only contains double-byte data, with no SO or SI delimiters surrounding it. The ONLYS field only contains double-byte character data within an SO/SI pair. The EITHER field can consist of double-byte character or single-byte character data but only one type at a time. If double-byte character data is present, it must be surrounded by an SO/SI pair. The OPEN field can consist of a mixture of double-byte character and single-byte character data. If double-byte character data is present, it must be surrounded by an SO/SI pair.

One cannot change the offset in a data pointer directly. To change the offset of a data pointer, you must first convert it into a SPCPTR by MI instruction SETSPPFP. To set the modified virtual address back to a data pointer, you should use Set Data Pointer Addressability (SETDPADR).

Data pointers can be used to manipulate indeterminate scalar data objects in OPM programs. For example, Copy Bytes Left-Adjusted (CPYBLA) accepts either data pointer operands or scalar operands. By modifying the attribute of a data pointer operand using Set Data Pointer Attributes (SETDPAT), you might determine the number of bytes really copied by instruction CPYBLA at run time. In contrast, in OPM programs, data pointers are far less often used in ILE HLL programs. Below is an example of using data pointers as operands to instruction Copy Extended Characters Left-Adjusted with Pad (CPYECLAP). This instruction copies data between extended (double-byte) character fields with padding or truncation. CPYECLAP accepts two data pointer operands as the receiver and source operand, respectively, and a padding operand that indicates the single-byte padding character and the double-byte padding character. The following is the prototype of instruction CPYECLAP extracted from mih52.rpgleinc.

The following ILE RPG example program t060.rpgle demonstrates the difference between copying an OPEN character field with truncation using ILE RPG operation code EVAL and using instruction CPYECLAP.

Code Notes:

(1) Scalar attributes of the receiver field are represented by data pointer rcv_ptr. Scalar attributes of the source field are represented by data pointer src_ptr.

(2) Copy OPEN field yes to OPEN field answer using ILE RPG operation code EVAL directly. Since the copy operation is unaware of the character attribute of the receiver field, the SI character is truncated by EVAL, and the resulting data content in field answer becomes invalid.

(3) Set scalar attributes into data pointers using Set Data Pointer (SETDP).

(4) Copy OPEN field yes to OPEN field answer with truncation using CPYECLAP. The last double-byte character (OK) is truncated and an SI character is appended properly to indicate the end of the double-bytes string in field answer.

Run ILE RPG program T060, and you'll get this result.

Invocation Pointers

An invocation pointer identifies a specific call stack entry in the call stack of a thread. Invocation pointers are primarily used in exception management MI instructions, such as Return from Exception (RTNEXCP), and message-handling APIs, such as the Promote Message (QMHPRMM) API. An example of using invocation pointers and label pointers to perform a non-local goto is available in section "Label Pointers."

Procedure Pointers

A procedure pointer identifies a specific instance of an ILE procedure within the scope of an MI process. Attributes of a procedure pointer include the following:

• Containing program—A system pointer to the ILE program object (of type either *PGM or *SRVPGM) that contains the procedure
• Containing process—A system pointer to the process control space object that contains the procedure's activation group
• An activation group mark of the activation group that contains the activated procedureAn activation mark of the activation of the ILE program that contains the activated procedure
• Module number—Index in the module list of the ILE program for the module whose activation the pointer addresses
• Procedure number—Index in the procedure list of the module for the procedure addressed by the pointer

After a procedure pointer is returned by an HLL operation loading the address of a procedure (such as invoking BIF %paddr and passing a prototype name in ILE RPG) or returned by MI instruction Materialize Activation Export (MATACTEX), procedure pointer calls can be made via the returned procedure pointer.

Here is an example of making procedure pointer calls via procedure pointers materialized by MATACTEX from a service program object. The following is the source code of ILE RPG program t061.rpgle. ILE RPG prototypes of instruction RSLVSP, ACTBPGM, and MATACTEX can be found in mih52.rpgleinc.

Code Notes:

(1) The prototype of procedure haha is exported by service program MAR14A. Here, procedure haha is declared based on procedure haha_ptr.

(2) Resolve the system pointer mar14a to service program MAR14A.

(3) Activate MAR14A by using MI instruction Activate Bound Program (ACTBPGM).

(4) Materialize procedure pointer to procedure haha using MI instruction MATACTEX.

(5) Call procedure haha via the returned procedure pointer.

Instruction Pointers

An instruction pointer identifies a specific instruction in the instruction stream of an OPM program by instruction number. An instruction pointer is one of the possible branch targets of OPM MI instruction Branch (B). The other valid branch targets of instruction B are an instruction number, a relative instruction number, a branch point (a label), or an element of an instruction definition list (an IDL is an array of labels).

The benefit of an instruction pointer is that, among all the possible branch targets, an instruction pointer is the only variable one. You can use Set Instruction Pointer (SETIP) to set or change the value of an instruction pointer at run time.

Also, an instruction pointer is used as the return-target operand of the OPM MI instruction Call Internal (CALLI). The CALLI instruction sets the instruction pointer operand to point to the instruction immediately following the CALLI instruction. Later, a Branch (B) instruction can be issued on this instruction pointer in the called sub-invocation to cause the control to be passed back to the instruction immediately following the CALLI instruction.

Label Pointers

A label pointer is somewhat the counterpart of an instruction pointer in ILE programs. A label pointer identifies a specific statement in an ILE procedure by statement ID. (A statement ID is a compiler-provided 4-byte unsigned binary value.) A label pointer has the following attributes:

• Containing program—System pointer to the program object that contains the label pointer
• Module number—Index in the module list of the bound program for the module containing the label pointer
• Procedure number—Index in the procedure list of the module for the procedure containing the label pointer
• Internal identifier—A machine-dependent value that identifies the label relative to the internal structure of the program (for use by service personnel)
• Statement ID—Each statement ID is a compiler-supplied unsigned bin(4) number that allows the compiler to identify the source statement associated with a particular sequence of instructions

To generate a label pointer to the current statement in an ILE procedure, you might use system built-in __setjmp or __setjmp2. __setjmp2 generates a label pointer to the current statement in an ILE procedure, while __setjmp additionally generates an invocation pointer to the current ILE procedure. The invocation pointer and label pointer saved by __setjmp can be used later by invoking ILE C function longjmp in another procedure to restore the saved stack environment and return control to the point identified by the saved invocation pointer and label pointer. The values of all variables (except register variables) available to the procedure receiving control contain the values they had when the longjmp function was called. Prototypes of system built-in __setjmp and __setjmp2 are extracted from mih52.rpgleinc.

The following is an example ILE RPG program, t063.rpgle, that demonstrates the usage of system built-in __setjmp and ILE C function longjmp.

Code Notes:

(1) Save the current invocation entry and statement ID into the invocation pointer and label pointer in structure pos of type jump_buf_t. __setjmp returns 0 after saving the invocation pointer and label pointer. If __setjmp returns as a result of a call to longjmp(), it returns the second argument to longjmp() or 1 if the second argument passed to longjmp() is 0.

(2) Call longjmp() to restore the stack environment.

Note that some MI instructions, but not all, can be invoked from ILE HLL programs. In IBM's documentation of HLLs, these MI instructions are referred to as "system built-ins." To distinguish between these MI instructions and those of common HLL procedures, ILE HLLs add an underscore (_) before their MI instruction names, conventionally. For example, the system built-in name of MI instruction FNVINXEN is "_FNDINXEN". Some system built-ins can be used only in ILE HLL programs. For example, __setjmp and __setjmp2.

Suspend Pointers

A suspend pointer identifies a suspend point or a resume point. It is a location within an invocation's routine where execution was suspended due to a call, an interrupt, or a machine operation. A resume pointer is a location within an invocation's routine where execution will resume if execution is allowed to resume in the invocation. A suspend pointer has the following attributes:

• Containing program—A system pointer to the program object that contains the suspend point or resume point
• Module number—Index in the module list of the bound program for the module containing the suspend point or resume point
• Procedure number—Index in the procedure list of the module for the procedure containing the suspend point or resume point
• Number of statement IDs—Number of entries in the statement ID list (multiple statement IDs may be associated with a single location in the created program due to optimizations that combine similar code sequences)
• Statement ID—A compiler-supplied, 4-byte unsigned binary number that allows the compiler to identify the source statement associated with a particular sequence of MI instructions
• Internal identifier—A machine-dependent value that locates the suspend point or resume point relative to the internal structure of the program (for use by service personnel)

MI instruction Materialize Invocation Attributes (MATINVAT) can be used to materialize the suspend point and resume point of a particular invocation.

Synchronization Pointers

A synchronization pointer is utilized by pointer-based mutexes that can be manipulated through mutex management MI instructions and POSIX semaphores implemented by i5/OS. When a named or unnamed pointer-based mutex or a POSIX semaphore is created, a synchronization pointer is generated by the system to identify the instance of one of the two synchronization primitives. For example, when a pointer-based mutex is created by using Create Pointer-Based Mutex (CRTMTX), a synchronization pointer is created based on CRTMTX's first space pointer operand. By using MI instruction MATPTR, you can tell which type of synchronization primitive is represented by a synchronization pointer: a pointer-based mutex or a POSIX semaphore.

Summary

As an OS-level virtual machine interface, the design of the MI layer originated from S/38, the direct ancestor of i5/OS. It is a creative and alive design that not only decouples application programs and hardware architectures, but also hides the implementation details of system objects behind a set of relatively stable interfaces. There's no doubt that it is a design ahead of the times. If you decided to learn more about this charming design, understanding the MI pointers may be a good start point.

Appendixes

Appendix A: ILE RPG Prototype of Independent Index Management Instructions

The following ILE RPG prototypes of independent index management instructions are extracted from mih52.rpgleinc; ILE RPG header for MI instructions (system built-ins) are provided by the open source project i5/OS Programmer's Toolkit.

Appendix B: Example of Using MI Instruction Activate Program (ACTPG)

Activate Program (ACTPG) creates an activation entry for the OPM program that is identified by a resolved system pointer, if it uses static storage. If the program specified is of any other type, an invalid operation for program (hex 2C15) exception is signaled. No operation is performed for a program that does not require static storage.

The following is the ILE RPG prototype extracted from mih52.rpgleinc.

If an activation entry is created or an activation entry already exists for the program within the target activation group, a space pointer to the static storage frame is returned. The static storage frame is allocated and initialized according to specifications within the program. The static storage frame is 16-byte aligned and begins with a 64-byte header. The header is not initialized and is not used by the machine. The header is provided for compatibility with prior machine implementations. If the program does not use static storage (hence, no activation entry is created), a copy of the program pointer in operand 2 is returned.

In the following examples, ILE RPG program T054 activates OPM program SPR1_A, which contains a static variable hello of type char(32) and with initial value "hello, hello, hello how are you?" Here's the code of the little MI program, SPR1_A.

To compile the little MI program, you can either use MI compilers such as mic provided by the open-source project i5/OS Programmer's Toolkit or call the Create Program (QPRCRTPG) API directly. For example, to avoid storing the source lines to a source physical file member or a stream file, you might invoke mic from QShell and input the source code directly from the standard input.

Or you can call the QPRCRTPG API to compile OPM program SPR1_A directly.

Here's the source code of ILE RPG program T054. Please refer to t054.rpgle for the latest version.

Code Notes:

(1) This is the layout of an OPM program's static storage frame (SSF) described by data structure ssf_t.

(2) Resolve system pointer pgm to OPM program SPR1_A.

(3) Activate OPM program SPR1_A using ACTPG, and then access storage in SSF of SPR1_A.

When you invoke ILE RPG program T054, you will receive this greeting from OPM program SPR1_A:

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

Advanced/Free - Function Calls and Return Values

PRACTICAL ILE - ILE Service Programs

Data-Manipulation Operations Using Free Format, Part Two