Open the door to the OMI program template.

In a post in the MI400-L mailing list at midrange.com, Simon Coulter documented the Materialize Program (QSCMATPG) and Create Program (QSCCRTPG) APIs in detail, including the parameter lists and related usage notes. Simon also designed a couple of CL commands to make it easier and more secure to use these APIs. With this information, you can open the door to the Original MI (OMI) program template, which allows a System/38 program to survive all the hardware changes and run on the most current IBM i release without recompilation.

There's no doubt that Machine Interface (MI) is one of the cornerstones of System/38 and its descendants (AS/400, iSeries, System i, and IBM i). As a high-level, virtual instruction set, it isolates the application software and most of the operating system from hardware dependencies. Since the introduction of New MI (NMI), on which the Integrated Language Environment (ILE) program model is based, the previous MI instruction set is referred to as OMI. And an MI transformer was introduced to convert OMI instruction streams to NMI instruction streams. This way, either old or newly developed Original Program Model (OPM) programs can still run on current or future IBM i releases. Search for NMI in the mailing list archive of MI400-L, you'll find a lot of discussion about OMI and NMI.

The key that a program created on one IBM i release (even System/38) can run on future IBM i releases with no need of recompilation is the intermediate representation of the program that is stored in the program object, the program template (the OMI program template for an OPM program or the NMI program template for an ILE program).The ability to obtain the MI program template is obviously one of the prerequisites to the goal of understanding the MI architecture. A couple of undocumented APIs in existence since S/38, the QSCMATPG and QSCCRTPG APIs, can be used to retrieve the OMI program template of an OPM program to a physical file and create an OPM program from the OMI program template stored in a physical file, respectively.

Simon's Post That Documented the QSCMATPG and QSCCRTPG APIs

The following is Simon's original post:

Re: QSCMATPG and QSCCRTPG

   * Subject: Re: QSCMATPG and QSCCRTPG

   * From: "Simon Coulter" <shc@xxxxxxxxxxxxxxxxx>;

   * Date: Wed, 30 May 01 21:02:57 +1000

To All,

I found some old notes of mine regarding these programs so I thought I would incorporate them in the documentation I sent earlier. The updates incorporate the supported special values and Gene's comment regarding LVLCHK(*NO). At the end you will find CMD and CL source for using them which I wrote years ago, hence the code to cope with S/38 -- remember that :)

QSCMATPG

   ---------------------------------------------

   | 1 | Program name   | Input   | CHAR(10) |

   ---------------------------------------------

   | 2 | Library name   | Input   | CHAR(10) |

   ---------------------------------------------

   | 3 | File name       | Input   | CHAR(10) |

   ---------------------------------------------

   | 4 | File library   | Input   | CHAR(10) |

   ---------------------------------------------

   | 5 | Member name     | Input   | CHAR(10) |

   ---------------------------------------------

   | 6 | Member option   | Input   | CHAR(8)   |

   ---------------------------------------------

The Materialize Program (QSCMATPG) API retrieves the program template for an OPM program and places it in the specified file member.

Program name: The name of the program to materalize.

Library name: The name of the library containing the program. *LIBL is supported.

File name: The name of the output file. This is a physical file with a record length of 80 bytes and LVLCHK(*NO). The file must exist before the API is called.

File library: The name of the library containing the output file. *LIBL is supported.

Member name: The name of the member to receive the program template. *PGM causes the program template to be stored in a member with the same name as the program.

Member option: *ADD or *REPLACE

QSCCRTPG

   ---------------------------------------------

   | 1 | Program name   | Input   | CHAR(10) |

   ---------------------------------------------

   | 2 | Library name   | Input   | CHAR(10) |

   ---------------------------------------------

   | 3 | File name       | Input   | CHAR(10) |

   ---------------------------------------------

   | 4 | File library   | Input   | CHAR(10) |

   ---------------------------------------------

   | 5 | Member name     | Input   | CHAR(10) |

   ---------------------------------------------

The Create Program (QSCCRTPG) API creates a program from the program template retrieved by the Materialise Program (QSCMATPG) API.

Program name: The name of the program to create.

Library name: The name of the library to contain the program. Special values are not supported.

File name: The name of the file containing the program template. This is a physical file with a record length of 80 bytes. The file must exist before the API is called.

File library: The name of the library containing the file. *LIBL is supported.

Member name: The name of the member containing the program template. *PGM uses a member with the same name as the program.

Example code:

MATPG:     CMD       PROMPT('Materialise Program Template')

             PARM       KWD(PGM) TYPE(Q1) MIN(1) PROMPT('Program')

             PARM       KWD(FILE) TYPE(Q2) MIN(1) PROMPT('File')

             PARM       KWD(MBR) TYPE(*NAME) DFT(*PGM) SPCVAL((*PGM) +

                         (*FILE)) EXPR(*YES) PROMPT('Member')

             PARM       KWD(MBROPT) TYPE(*CHAR) LEN(8) RSTD(*YES) +

                         DFT(*REPLACE) VALUES(*REPLACE *ADD) +

                         PROMPT('Replace or add records')

Q1:         QUAL       TYPE(*NAME) MIN(1) EXPR(*YES)

             hUAL       TYPE(*NAME) DFT(*LIBL) SPCVAL((*LIBL)) +

                         EXPR(*YES) PROMPT('Library')

Q2:         QUAL       TYPE(*NAME) MIN(1) EXPR(*YES)

             QUAL       TYPE(*NAME) DFT(*CURLIB) SPCVAL((*CURLIB +

                         *CURLIB) (*LIBL)) EXPR(*YES) +

                         PROMPT('Library')

MATPGC:     PGM       PARM(&QUALPGM &QUALFILE &MBR &MBROPT)

/*                                                                 */

/*----------------- Input Parameter Declarations ------------------*/

/*                                                                 */

             DCL       VAR(&QUALPGM) TYPE(*CHAR) LEN(20)

             /* NameLibrary */

             DCL       VAR(&QUALFILE) TYPE(*CHAR) LEN(20)

             /* NameLibrary */

            DCL       VAR(&MBR) TYPE(*CHAR) LEN(10)

             /* Work file member */

             DCL       VAR(&MBROPT) TYPE(*CHAR) LEN(8)

             /* *ADD or *REPLACE */

/*                                                                 */

/*-------------------- Program Declarations -----------------------*/

/*                                                                 */

             DCL       VAR(&PGM) TYPE(*CHAR) LEN(10)

             DCL       VAR(&PLIB) TYPE(*CHAR) LEN(10)

             DCL       VAR(&FILE) TYPE(*CHAR) LEN(10)

             /* Program template work file */

             DCL       VAR(&FLIB) TYPE(*CHAR) LEN(10)

             /* Work file library */

             DCL       VAR(&REALLIB) TYPE(*CHAR) LEN(10) /* Actual +

                          library containing program (for *LIBL +

                         search) */

             DCL       VAR(&MSGTYPE) TYPE(*CHAR) LEN(5)

             DCL       VAR(&IGC) TYPE(*CHAR) LEN(1)

/*                                                                */

/*----------------- Mnemonic Value Declarations -------------------*/

/*                                                                 */

             DCL       VAR(&BLANK) TYPE(*CHAR) LEN(1) VALUE(X'40')

                       /* Mnemonic for 'blank' */

             DCL       VAR(&TRUE) TYPE(*LGL) LEN(1) VALUE('1')

                       /* Mnemonic for 'true' */

             DCL       VAR(&FALSE) TYPE(*LGL) LEN(1) VALUE('0')

                       /* Mnemonic for 'false' */

            DCL       VAR(&ERROR) TYPE(*LGL) LEN(1)

                       /* Mnemonic for 'error' */

/*                                                                 */

/*-------------- Global Message Monitor Declarations --------------*/

/*                                                                */

             DCL       VAR(&MSGDTA) TYPE(*CHAR) LEN(40)

             DCL       VAR(&MSGID) TYPE(*CHAR) LEN(7)

             DCL       VAR(&MSGF) TYPE(*CHAR) LEN(10)

             DCL       VAR(&MSGFLIB) TYPE(*CHAR) LEN(10)

/*                                                                 */

/*--------------- Global Message Monitor Intercept ----------------*/

/*                                                                 */

             MONMSG     MSGID(CPF0000 MCH0000) EXEC(GOTO CMDLBL(ERROR))

/* Substring out the program and library names */

             CHGVAR     VAR(&PGM) VALUE(%SST(&QUALPGM 1 10))

             CHGVAR     VAR(&PLIB) VALUE(%SST(&QUALPGM 11 10))

             CHGVAR     VAR(&REALLIB) VALUE(&PLIB)

             CHGVAR     VAR(&FILE) VALUE(%SST(&QUALFILE 1 10))

             CHGVAR     VAR(&FLIB) VALUE(%SST(&QUALFILE 11 10))

/* Handle special values from command definition */

             IF         COND(&MBR *EQ '*PGM') THEN(DO)

              CHGVAR     VAR(&MBR) VALUE(&PGM)

             ENDDO

             IF         COND(&MBR *EQ '*FILE') THEN(DO)

               CHGVAR     VAR(&MBR) VALUE(&FILE)

             ENDDO

/* ********************************************************** */

/* If '*LIBL' was passed in for library, get the name of the */

/* actual library containing the program.                     */

/*                                                           */

/* The trick to determining the library of an existing object */

/* is as follows:                                             */

/*                                                           */

/* 1. Rename the object to itself                           */

/* 2. CPF returns a message informing that the object was    */

/*     not renamed.                                         */

/*     On the AS/400, an escape message is sent.             */

/*     On the S/38, an informational message is sent         */

/*     This code section works on either machine.            */

/* 3. The library of the object is in positions 11 - 20     */

/*     of the message data associated with the message.     */

/* ********************************************************** */

             IF         COND(&REALLIB *EQ '*LIBL') THEN(DO)

               CHGVAR     VAR(&MSGTYPE) VALUE('*INFO')

               RNMOBJ     OBJ(&PGM) OBJTYPE(*PGM) NEWOBJ(&PGM)

               MONMSG     MSGID(CPF2132) EXEC(DO)

                 CHGVAR     VAR(&MSGTYPE) VALUE('*EXCP')

               ENDDO

               RCVMSG     MSGTYPE(&MSGTYPE) MSGDTA(&MSGDTA) MSGID(&MSGID)

               CHGVAR     VAR(&REALLIB) VALUE(%SST(&MSGDTA 11 10))

             ENDDO     /* RealLib */

/* Allocate the program */

             ALCOBJ     OBJ((&REALLIB/&PGM *PGM *EXCL))

/* Ensure work file and member exist */

             CHKOBJ     OBJ(&FLIB/&FILE) OBJTYPE(*FILE)

             MONMSG     MSGID(CPF9801) EXEC(DO)

               RCVMSG     MSGTYPE(*LAST)

               RTVSYSVAL SYSVAL(QIGC) RTNVAR(&IGC)

              IF         COND(&IGC *EQ '1') THEN(DO)

                 CRTPF     FILE(&FLIB/&FILE) RCDLEN(80) MBR(&MBR) +

                             TEXT('Work file for MATPG/CRTPG command.'h +

                             OPTION(*NOLIST *NOSOURCE) MAXMBRS(*NOMAX) +

                             SIZE(*NOMAX) LVLCHK(*NO) IGCDTA(*YES)

               ENDDO

               ELSE       CMD(DO)

                 CRTPF     FILE(&FLIB/&FILE) RCDLEN(80) MBR(&MBR) +

                             TEXT('Work file for MATPG/CRTPG command.') +

                             OPTION(*NOLIST *NOSOURCE) MAXMBRS(*NOMAX) +

                             SIZE(*NOMAX) LVLCHK(*NO)

               ENDDO

             ENDDO

             CLRPFM     FILE(&FLIB/&FILE) MBR(&MBR)

             MONMSG     MSGID(CPF3141) EXEC(DO)

               RCVMSG     MSGTYPE(*LAST)

               ADDPFM     FILE(&FLIB/&FILE) MBR(&MBR)

             ENDDO

/* ************************************************************ */

/* Call the CPF module to materialise the program.             */

/* This will convert the internal representation of the program */

/* into an external form we can modify.                         */

/* The materialised information is placed in the work file.     */

/* Note:- this interface is not supported after V2R1.1.         */

/* ************************************************************ */

             CALL       PGM(QSCMATPG) PARM(&PGM &REALLIB &FILE +

                         &FLIB &MBR &MBROPT)

/*                                                                */

/*--------------------- Send User a Message -----------------------*/

/*                                                                 */

             SNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) +

                         MSGDTA('Program' *BCAT &PGM *BCAT 'in' +

                         *BCAT &REALLIB *BCAT 'materialised in +

                         member' *BCAT &MBR *BCAT 'in file' *BCAT +

                         &FILE *BCAT 'in' *BCAT &FLIB) MSGTYPE(*COMP)

EXIT:       RETURN     /* Normal end of program */

/*                                                                 */

/*---------------------- Exception Routine ------------------------*/

/*                                                                 */

ERROR:      RCVMSG     MSGTYPE(*EXCP) MSGDTA(&MSGDTA) MSGID(&MSGID) +

                         MSGF(&MSGF) MSGFLIB(&MSGFLIB)

             MONMSG     MSGID(CPF0000 MCH0000) EXEC(RETURN)

                       /* Just in case */

             IF         COND(&MSGID *NE &BLANK) THEN(DO)

             SNDPGMMSG MSGID(&MSGID) MSGF(&MSGFLIB/&MSGF) +

                         MSGDTA(&MSGDTA) MSGTYPE(*ESCAPE)

             MONMSG     MSGID(CPF0000 MCH0000) EXEC(RETURN)

                       /* Just in case */

            ENDDO

MATPGX:     ENDPGM

CRTPG:     CMD       PROMPT('Create Program from Template')

             PARM       KWD(PGM) TYPE(Q1) MIN(1) PROMPT('Program')

             PARM       KWD(FILE) TYPE(Q2) MIN(1) PROMPT('File')

             PARM       KWD(MBR) TYPE(*NAME) DFT(*PGM) SPCVAL((*PGM) +

                         (*FILE)) EXPR(*YES) PROMPT('Member')

Q1:         QUAL       TYPE(*NAME) MIN(1) EXPR(*YES)

             QUAL       TYPE(*NAME) DFT(*CURLIB) SPCVAL((*CURLIB +

                         *CURLIB)) EXPR(*YES) PROMPT('Library')

Q2:         QUAL       TYPE(*NAME) MIN(1) EXPR(*YES)

             QUAL       TYPE(*NAME) DFT(*LIBL) SPCVAL((*LIBL) +

                         (*CURLIB *CURLIB)) EXPR(*YES) +

                         PROMPT('Library')

CRTPGC:     PGM       PARM(&QUALPGM &QUALFILE &MBR)

/*                                                                 */

/*----------------- Input Parameter Declarations ------------------*/

/*                                                                */

             DCL       VAR(&QUALPGM) TYPE(*CHAR) LEN(20)

             /* NameLibrary */

             DCL       VAR(&QUALFILE) TYPE(*CHAR) LEN(20)

             /* NameLibrary */

             DCL       VAR(&MBR) TYPE(*CHAR) LEN(10)

             /* Work file member */

/*                                                                 */

/*-------------------- Program Declarations -----------------------*/

/*                                                                 */

              DCL       VAR(&PGM) TYPE(*CHAR) LEN(10)

             DCL       VAR(&PLIB) TYPE(*CHAR) LEN(10)

             DCL       VAR(&FILE) TYPE(*CHAR) LEN(10)

             /* Program template work file */

             DCL       VAR(&FLIB) TYPE(*CHAR) LEN(10)

             /* Work file library */

             DCL       VAR(&REALLIB) TYPE(*CHAR) LEN(10) /* Actual +

                           library containing file (for *LIBL +

                           search) */

             DCL       VAR(&MSGTYPE) TYPE(*CHAR) LEN(5)

             DCLF       FILE(QADSPOBJ)

/*                                                                 */

/*----------------- Mnemonic Value Declarations -------------------*/

/*                                                                */

             DCL       VAR(&BLANK) TYPE(*CHAR) LEN(1) VALUE(X'40')

                       /* Mnemonic for 'blank' */

             DCL       VAR(&TRUE) TYPE(*LGL) LEN(1) VALUE('1')

                       /* Mnemonic for 'true' */

            DCL       VAR(&FALSE) TYPE(*LGL) LEN(1) VALUE('0')

                       /* Mnemonic for 'false' */

             DCL       VAR(&ERROR) TYPE(*LGL) LEN(1)

                       /* Mnemonic for 'error' */

/*                                                                */

/*-------------- Global Message Monithr Declarations --------------*/

/*                                                                 */

             DCL       VAR(&MSGDTA) TYPE(*CHAR) LEN(40)

             DCL       VAR(&MSGID) TYPE(*CHAR) LEN(7)

             DCL       VAR(&MSGF) TYPE(*CHAR) LEN(10)

             DCL       VAR(&MSGFLIB) TYPE(*CHAR) LEN(10)

/*                                                                 */

/*--------------- Global Message Monitor Intercept ----------------*/

/*                                                                 */

             MONMSG     MSGID(CPF0000 MCH0000) EXEC(GOTO CMDLBL(ERROR))

/* Substring out the program and library names */

             CHGVAR     VAR(&PGM) VALUE(%SST(&QUALPGM 1 10))

             CHGVAR     VAR(&PLIB) VALUE(%SST(&QUALPGM 11 10))

             CHGVAR     VAR(&FILE) VALUE(%SST(&QUALFILE 1 10))

             CHGVAR     VAR(&FLIB) VALUE(%SST(&QUALFILE 11 10))

             CHGVAR     VAR(&REALLIB) VALUE(&FLIB)

/* Handle special values from command definition */

             IF         COND(&MBR *EQ '*PGM') THEN(DO)

               CHGVAR     VAR(&MBR) VALUE(&PGM)

             ENDDO

             IF         COND(&MBR *EQ '*FILE') THEN(DO)

                CHGVAR     VAR(&MBR) VALUE(&FILE)

             ENDDO

/* ********************************************************** */

/* If '*LIBL' was passed in for library, get the name of the */

/* actual library containing the file.                        */

/*                                                           */

/* The trick to determining the library of an existing object */

/* is as follows:                                             */

/*                                                            */

/* 1. Rename the object to itself                           */

/* 2. CPF returns a message informing that the object was   */

/*     not renamed.                                         */

/*     On the AS/400, an escape message is sent.              */

/*     On the S/38, an informational message is sent         */

/*     This code section works on either machine.             */

/* 3. The library of the object is in positions 11 - 20     */

/*     of the message data associated with the message.     */

/* ********************************************************** */

             IF         COND(&REALLIB *EQ '*LIBL') THEN(DO)

               CHGVAR     VAR(&MSGTYPE) VALUE('*INFO')

               RNMOBJ     OBJ(&FILE) OBJTYPE(*FILE) NEWOBJ(&FILE)

               MONMSG     MSGID(CPF2132) EXEC(DO)

                 CHGVAR     VAR(&MSGTYPE) VALUE('*EXCP')

               ENDDO

               RCVMSG     MSGTYPE(&MSGTYPE) MSGDTA(&MSGDTA) MSGID(&MSGID)

               CHGVAR     VAR(&REALLIB) VALUE(%SST(&MSGDTA 11 10))

             ENDDO     /* RealLib */

/* Allocate the program */

             ALCOBJ     OBJ((&PLIB/&PGM *PGM *EXCL))

             MONMSG     MSGID(CPF1085) EXEC(DO)

               RCVMSG     MSGTYPE(*EXCP)                 h

              GOTO       CMDLBL(CREATE) /* Not found */

             ENDDO

/* Ensure work file and member exist */

             CHKOBJ     OBJ(&REALLIB/&FILE) OBJTYPE(*FILE) MBR(&MBR)

/* Find out the current owner of the object */

             DSPOBJD   OBJ(&PLIB/&PGM) OBJTYPE(*PGM) +

                         DETAIL(*SERVICE) OUTPUT(*OUTFILE) +

                         OUTFILE(QTEMP/@RTVPGMOWN)

             OVRDBF     FILE(QADSPOBJ) TOFILE(QTEMP/@RTVPGMOWN)

             RCVF

/* Delete the existing program */

             DLTPGM     PGM(&PLIB/&PGM)

/* ************************************************************ */

/* Call the CPF module to recreate the program from the update */

/* program template.                                           */

/* Note:- this interface is not supported after V2R1.1.         */

/* ************************************************************ */

CREATE:     CALL       PGM(QSCCRTPG) PARM(&PGM &PLIB &FILE +

                         &REALLIB &MBR)

/* Ensure the original owner still owns the program */

/* Note:- Need to adopt GOD to ensure this works   */

             IF         COND(&ODOBOW *NE &BLANK) THEN(DO)

               CHGOBJOWN OBJ(&REALLIB/&PGM) OBJTYPE(*PGM) +

                           NEWOWN(&ODOBOW)

           ENDDO

/*                                                                 */

/*--------------------- Send User a Message -----------------------*/

/*                                                                 */

             SNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) +

                         MSGDTA('Program' *BCAT &PGM *BCAT 'in' +

                         *BCAT &REALLIB *BCAT 'created from +

                         member' *BCAT &MBR *BCAT 'in file' *BCAT +

                         &FILE *BCAT 'in' *BCAT &FLIB) MSGTYPE(*COMP)

EXIT:       RETURN     /* Normal end of program */

ERROR:     RCVMSG     MSGTYPE(*EXCP) MSGDTA(&MSGDTA) MSGID(&MSGID) +

                         MSGF(&MSGF) MSGFLIB(&MSGFLIB)

             MONMSG     MSGID(CPF0000 MCH0000) EXEC(RETURN)

                       /* Just in case */

             IF         COND(&MSGID *NE &BLANK) THEN(DO)

             SNDPGMMSG MSGID(&MSGID) MSGF(&MSGFLIB/&MSGF) +

                         MSGDTA(&MSGDTA) MSGTYPE(*ESCAPE)

             MONMSG    MSGID(CPF0000 MCH0000) EXEC(RETURN)

                       /* Just in case */

             ENDDO

CRTPGX:     ENDPGM

Regards,

Simon Coulter.

The source of the MATPG and CRTPG CL commands and their Command Processing Programs are available as matpg.cl-cmd, crtpg.cl-cmd, matpgc.clp, and crtpgc.clp.

To retrieve the OMI program template of an OPM program, you can issue the following command:

MATPG PGM(MYOPMPGM) FILE(OMI)

This will place the materialized OPM program template of *LIBL/MYOPMPGM into physical file member *CURLIB/OMI(MYOPMPGM). To create an OPM program from an existing OPM program template stored in a physical file member, you can issue the following command:

CRTPG PGM(MYOPMPGM) FILE(OMI) MBR(MBR_NAME)

To display the materialized OMI program templates, you can use the Source Entry Utility (SEU) or the Display File (DSPF) command. However, it would be a little inconvenient to browse the hexadecimal content of the program template with either of these tools. There's a tiny tool program PRTHEX80 (whose source code is available as prthex80.c at i5/OS Programmer's Toolkit) that prints the content of a physical file member in a format similar to SST to an output spooled file. For example, to print the content of the above-mentioned OMI program template of MYOPMPGM stored in physical file member *CURLIB/OMI(MYOPMPGM), you can call PRTHEX80 like so:

   CALL PRTHEX '*CURLIB/OMI(MYOPMPGM)'

or

 CALL PRTHEX 'OMI(MYOPMPGM)'

The output spooled file of PRTHEX80 might look like the following:

Understand the Output of the QSCMATPG API

The output of the QSCMATPG API is composed of not only the OMI program template, but also several other components. Gene Gaunt gave the names and meaning of these components in a post in the same discussion thread as following:

Re: QSCMATPG and QSCCRTPG

   * Subject: Re: QSCMATPG and QSCCRTPG

   * From: gene_gaunt@xxxxxxxxxxxxxxx>

   * Date: Tue, 29 May 2001 09:22:50 -0400

Looks like QSCMATPG gets more than program creation template into a file:

PT section: program creation template

AS section: associated space

TX section: object description

SC section: service data

AU section: authority bits

A short investigation into the above-shown example output of QSCMATPG will prove Gene's assumption. Also, you can figure out the format of each section easily. Each QSCMATPG output section starts with a 16-byte header. The first two fields in this header are:

• CHAR(2) eye-catcher. Section type. Possible values are: PT, AS, TX, SC, AU (more?)
• BIN(4) section length. Length of the current section (not including the length of the 16-byte header)

Since the QSCMATPG output sections are self-described, a parser program can walk through the entire output with ease.

With more investigation, you might find out more details of the QSCMATPG output sections:

• PT section—OMI program template of the OPM program, which contains the following components: OMI Program template header, OMI instruction stream, ODT DIRECTORY VECTOR (ODV), ODT ENTRY STRING (OES), OPM high-level language symbol table, etc. The OMI Program template header contains OMI program attributes (such as object type, object name, number of OMI instructions, etc.) and length and offset values of other components.
• AS section—Associated space of the OPM program. For OPM CL programs created with parameter ALWRTVSRC set to *YES, the associated space will contain the complete CL source of the program.
• TX section—Text description in the OIR information of the program. To display the OIR information of an object, you can issue one of the Dump commands (DMPOBJ, DMPSYSOBJ, or DMP) against the object and search for OIR DATA in the result output.
• SC section—Service data within the program's OIR information.
• AU section—Public authority bits of the OPM program.

An Example of Modifying an OPM Program via the Retrieved OMI Program Template

While our purpose of retrieving the OMI program template is to study and learn from the design of MI, it's also possible to change an existing OPM program via the retrieved OMI program template. I'll provide a real example.

In VRM540, IBM introduces pointer variables to CL and related supports—for example, supports for based and defined CL variables. However before VRM710, when comparing two pointer values in an OPM CL program, if one of the pointers is a null pointer or both pointers are null pointers, the comparison will failed with a Pointer Does Not Exist exception (hex 2401, aka MCH3601). By compiling an OPM CL program that compares two pointer values with parameter GENOPT(*LIST), you will find out the reason from the MI source listing generated by the OPM CL compiler. Here's the compiler listing of an OPM CL program (at VRM540), a322.clp:

At statement 2600, pointer variables &P1 and &P2 are compared for equality. Corresponding OMI instructions generated by the OPM CL compiler (at VRM540) are the following:

Note: All the OMI instructions shown in this example are generated by the OPM CL compiler at VRM540.

Now you know the reason for the MCH3601 exception. Before the Compare Pointer for Space Addressability (CMPPSPAD) instruction is used to compare the addressability of space pointers &P1 and &P2, no action is adopted to test whether &P1 or &P2 is null pointer. If one of CMPPSPAD's operands is a null pointer, CMPPSPAD will raise a Pointer Does Not Exist exception (MCH3601). One possible (although quite far from practical) workaround is retrieving the OMI program template of the OPM CL program to a physical file via the QSCMATPG API, inserting OMI instructions that check for null pointers into the OMI instruction stream in the OMI program template, and finally re-creating the OPM CL program from the modified program template via the QSCCRTPG API. (Of course, if you only want to solve the MCH3601 problem, the simplest method is changing the OPM program that compares pointers into ILE CL.)

For information about the OMI program template and OMI instruction stream, please refer to the following resources:

• Program Object Specifications in the IBM i Information Center
• Analyzing the MI Instruction Stream of an OPM Program

Imagine that the original version of the OPM CL program (a322.clp) is the following. It compares the two input pointer parameters for equality and returns the comparison result in the CHAR(2) output parameter &RE.

To make sure neither pointer variable &P1 nor &P2 is a null pointer before statement 900 is executed, you may insert a couple of indicator form Compare Pointer Type (CMPPTRT) instructions to test for null pointer and store the test results in CL indicator variables. This allows you to check the test results in CL instead of inserting more MI instructions into the OMI instruction stream. The definitions of the CL indicator variables and CL statements checking them might look like the following:

Next, you need placeholder instructions in the OMI instruction stream of the CL program that occupies the same length as the CMPPTRT instructions so that you can simply replace the placeholder instructions with two CMPPTRT instructions. To test if a pointer is a null pointer, a branch form or indicator form CMPPTRT instruction can be issued against the target pointer setting operand 2 to hex 00. As you probably know, an indicator form CMPPTRT instruction contains five 2-byte fields (see "Analyzing the MI Instruction Stream of an OPM Program"); for example, the OMI instruction CMPPTRT(I) &P1, X'00' / EQ(&IN1) might look like the following in the compiled OMI instruction stream:

18E2 4000 0001 2000 0002   CMPPTRT(I) &P1, X'00' / EQ(&IN1)

The five 2-byte fields are:

• 18E2—Operation code of CMPPTRT (indicator form)
• 4000—Op-code extender. Indicates there is one group-3 resultant condition—in this case, <I>EQ—specified for the instruction
• 0001—ODT reference of space pointer <I>&P1 (operand 1 of the CMPPTRT instruction)
• 2000—Immediate operand hex 00 (operand 2 of the CMPPTRT instruction)
• 0002—ODT reference of indicator operand <I>&IN1

Comparing a numeric variable in OPM CL will generate an indicator form comparison instruction and a branch form comparison instruction (each occupies five 2-byte fields in the OMI instruction stream, the same with an indicator form CMPPTRT instruction). For example, OMI instructions generated for an OPM CL statement IF COND(&B *GT 78) THEN(...) might look like this:

So a numeric comparison CL statement would be a perfect placeholder for inserting two indicator form CMPPTRT instructions. The following is the modified version of a322.clp. Two CHAR(1) variables—&IN1 and &IN2—are added to receive the comparison result of the CMPPTRT instructions. The BIN(4) field &B is added and is compared to numeric value 78 for equality in statement 1600, which creates the do-nothing GOTO to label LALA after the comparison.

The MI instructions generated for statement 1600 (IF COND(&B *GT 78)) are the following:

Instructions /0B and /0C are the placeholders for the CMPPTRT instructions.

The ODT references of CL variables &IN1, &IN2, &OPT, &P1, and &P2 are the following:

0026 &IN1                   37 47 73*

0027 &IN2                   38 47 74*

0028 &OPT                   22 75*

0029 &P1                   58 76*

002A &P2                   58 77*

Now let's assemble the CMPPTRT instructions to test &P1 and &P2 for null pointers:

The final steps are replacing the placeholder instructions (/0B and /0C) in OPM CL program A322 with our newly assembled CMPPTRT instructions:

• Issue a <i>MATPG PGM(A322) FILE(OMI) MBR(A322) command to retrieve the OPM program template.
• Since the hexadecimal program template is hard to edit, you may need to convert it to character format first. A tiny tool program H2C80 (h2c80.c) reads each record of a physical file member with a record length of 80 bytes, converts hexadecimal content of the record to 160-byte character representation, and writes to a target physical file member with a record length of 160 bytes. Another tool program C2H80 (c2h80.c) does the reverse task of H2C80, i.e., converts 160-byte character records back to 80-byte hexadecimal representation. For example, the following commands will generate the character form program template in physical file member *CURLIB/OMIC(A322):
  
  

• Edit the (character form) OMI program template via the EDTF command and replace the placeholder instructions (/0B and /0C) in OPM CL program A322 with the newly assembled CMPPTRT instructions: replace 184610000025000E002E with 18E24000002900280026; replace 1CC2C000002E20F10010 with 18E24000002A00280027.
• Convert the edited OMI program template back to hexadecimal representation—for example, CALL C2H80 ('OMIC(A322)' 'OMI(A322)').
• Create a new program object A322X using the modified OMI program template via the CRTPG command provided by Simon: CRTPG PGM(A322X) FILE(OMI) MBR(A322).
• Test program A322 and its modified version (A322X) with the following test program, a322t.clp:
  
  

Call A322T and specify A322 as the target program to test. A322 would fail in the first test with MCH3601.

Test the re-created program A322X via A322T. All tests will complete successfully.

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 API Corner: Moving Jobs Within and Across Job Queues

The API Corner: What Time Zone Do You Want That Date and Time In?

The API Corner: How Do You Want That Date and Time?