i5/OS Programmer's Toolkit: System-builtin Headers and Examples for ILE HLLs

0.2.16

Go back to main page of project i5/OS Programmer's Toolkit .

With the introduction of ILE, HLLs can not only make external program calls and static procedure calls, but can also call MI instructions which expose bound program access interfaces to HLLs. In the documentation of the ILE RPG, MI instructions are often metioned as system-builtins.

IMHO, the benifits of using MI instructions in HLLs are the following:

MI instructions are effient.
Algorithms and funtionality provided by MI instructions are, sometimes necessary, supplements to HLLs or APIs.
It can help you knowing the operation system that you work with day after day better.

Remarks:: The RPG programming language is the most notable i5/OS HLL (High Level Language) and the name of this subproject was orginally "System-builtin Headers for ILE RPG". At release 0.2.16, supports in forms of example programs and/or copybooks are added for other ILE HLLs, such as ILE COBOL and ILE CL.

As a subproject of the open source project, i5/OS Programmer's Toolkit , here we are trying to provide headers (copybooks) in ILE RPG and ILE COBOL and usage example programs in RPG, COBOL, and CL for all documented system-builtins (MI instructions expose bound program access interfaces HLLs) until V5R4. By release 0.2.16, in the system-builitins header for ILE RPG, there are over 200 prototypes for system-builtins (MI instructions) and over 170 data structures by which instruction templates of MI instructions are described. Also, there're about 200 usage example programs for most MI instructions. Headers and usage examples for COBOL and CL are added at release 0.2.16 and are expected to cover nearly all documented system-builtins in a few future releases. List of System-builtins lists all systme-builtins currently being covered.

Note that this subproject provides only usage examples of MI instructions for ILE CL, but does not provide copybooks for ILE CL. Although in V6R1, ILE CL programs began to have the ability to include other source members via the INCLUDE command, and in V7R1 the nested INCLUDE support was added to ILE CL. But it's a sorrow that we have no access to an IBM i server with V6R1 or V7R1 installed to test what we produce.

Contents

Download and Install

You can download and install the system-builtin headers for ILE HLLs from the most recent release package of the project. The system-builtin headers for ILE HLLs can be restored to your system via bin/rpg.savf in a release package. All releases of i5/OS Programmer's Toolkit can be found at:

http://sourceforge.net/projects/i5toolkit/files/

Remarks:: Before release 0.2.16, system-builtin headers for ILE RPG are mih52.rpgleinc and mih54.rpgleinc. At release 0.2.16, prototypes of MI instructions and data structure definitions in these two huge headers were moved to new headers by category. And these two old headers became symbolic links to an all-in-one header, mih.rpgleinc, so that programs that included them do not need to be modified.

You can also download the lasted version of them by the following link and upload it to your system by FTP:

Or check them out from the project's svn repository like the following:

svn export https://i5toolkit.svn.sourceforge.net/svnroot/i5toolkit/rpg/
svn export https://i5toolkit.svn.sourceforge.net/svnroot/i5toolkit/cobol/
svn export https://i5toolkit.svn.sourceforge.net/svnroot/i5toolkit/cl/

Getting Started with System-builtin Headers for ILE HLLs

ILE RPG

Here is a simple ILE RPG program that materialize the HMC information via the MATMATR (Materialize Machine Attributes) intruction. It includes system-builtin header mih-pgmexec.rpgleinc and mih-spt.rpgleinc using compiler directive /COPY.

     /* *
      * @file t147.rpgle
      *
      * Test of _MATMATR1. Materialize HMC info.
      */
      /if defined(*crtbndrpg)
     h dftactgrp(*no)
      /endif

      /copy mih-pgmexec
      /copy mih-spt

     d tmpl            ds                  likeds(matmatr_hmc_t)
     d                                     based(ptr)
     d ptr             s               *
     d len             s             10i 0
     d opt             s              2a   inz(x'0204')

      /free
           ptr = modasa(8);
           tmpl.bytes_in = 8;
           matmatr(tmpl : opt);

           len = tmpl.bytes_out;
           ptr = modasa(len);
           tmpl.bytes_in = len;
           matmatr(tmpl : opt);
             // check the returned HMC info

           *inlr = *on;
      /end-free

     /* *
      * The returned HMC info might be like the following:
      * @code
      * > EVAL TMPL.HMC_INFO.INFO(1):x 100                
      *      00000     486D6353 7461743D 313B4873 634E616D
      *      00010     653D3730 34324352 342A3036 37344542
      *      00020     423B4873 63486F73 744E616D 653D6C6F
      *      00030     63616C68 6F73743B 48736349 50416464
      *      00040     723D3132 372E302E 302E313B 48736341
      *      00050     64644950 733D3B48 4D434164 64495076
      *      00060     36733D3B ........ ........ ........
      * @endcode
      *
      * Convert the above result into ASCII encoding, then the
      * result should be like the following:
      * 'HmcStat=1;... ...'
      */

To compile this program into a program object or a module object, use CL command CRTBNDRPG or CRTRPGMOD with the INCDIR parameter set to

INCDIR('/usr/local/include/rpg')

ILE COBOL

The following ILE COBOL program materialize the symbolic ID (program name and library name) of itself via the MATPGMNM (Materialize Program Name) instruction. It includes 3 copybooks totally:

mih-lnktyp.cblleinc in the SPECIAL-NAMES paragraph of the CONFIGURATION section of its ENVIRONMENT division
mih-pgmexec.cblleinc and mih-pgmmng.cblleinc in the WORKING-STORAGE section of its DATA division.

     /* *
      * @file cbl005.cblle
      *
      * Test of:
      *  - _MODASA
      *  - _MATPGMNM
      */
       process
           NOMONOPRC.

       id division.
       program-id. cbl005.

       environment division.
       configuration section.
       special-names.
           copy mih-lnktyp.

       data division.
       working-storage section.
       01 ptr pointer.
       01 asf-size pic 9(9) usage comp-4.
       01 zer constant as x"00".

       linkage section.
           copy mih-pgmexec.
           copy mih-pgmmng.

       01 pgm-info type matpgmnm-t.

       procedure division.

       main-pgm.
           move 80 to asf-size.
           call "_MODASA" using
               by value asf-size
               returning into ptr.
           call "_PROPB" using
               by value ptr
               by value zer
               by value asf-size.

           set address of pgm-info to ptr.
           move 80 to bytes-in of pgm-info.
           call "_MATPGMNM" using
               by reference pgm-info.
           display "i'm "
                   function trimr (context-name of pgm-info)
                   "/"
                   program-name of pgm-info.

       see-you.
           stop run.

      * output
      * i'm LSBIN/CBL005

To compile this program into a program object or a module object, use CL command CRTBNDCBL or CRTCBLMOD with the INCDIR parameter set to

INCDIR('/usr/local/include/cobol')

Remarks:

Note that the manner that the ILE COBOL compiler treats the source-path-name specified in a COPY statement is a little different from the ILE RPG compiler. When compiling a COBOL program from a source member with command CRTBNDCBL/CRTCBLMOD SRCFILE(...) SRCMBR(...), the COBOL compiler treats the source-path-name specified in a COPY statement as the name of a source member. So when the target source file to be included is a stream file in the IFS, the COBOL compiler would fail to load the target source file. To avoid this problem, use the SRCSTMF parameter instead of the SRCFILE and SRCMBR parameters to specify the IFS path name of your COBOL program. For example,

/* Compile from a stream source file */
CRTBNDCBL PGM(ABC) SRCSTMF('/home/a-cobol-pgmr/my-cbl-src/abc.cblle') INCDIR('/usr/local/include/cobol')

/* Compile from a source member */
CRTBNDCBL PGM(ABC) SRCSTMF('/qsys.lib/my_src.lib/cbl_src.file/abc.mbr') INCDIR('/usr/local/include/cobol')

ILE CL

Here is an sample ILE CL program provided by this subproject. It computes the time duration of 2 input times (in ISO time format) via the CTD (Compute Time Duration) instruction.

/* *                                                                           +
 * @file cl005.clle                                                            +
 *                                                                             +
 * Test of the following system builtins:                                      +
 *  - _CTD (Compute Time Duration)                                             +
 *                                                                             +
 * Call this program like the following:                                       +
 *   CALL CL005 ('15.11.05' '11.10.03')                                        +
 *                                                                             +
 * The result should be: &DURATION = 040102.                                   +
 */

             PGM        PARM(&EVENING &MORNING)
             DCL        VAR(&EVENING) TYPE(*CHAR) LEN(8) /* end time */
             DCL        VAR(&MORNING) TYPE(*CHAR) LEN(8) /* start +
                          time */
             DCL        VAR(&ISODURTMPL) TYPE(*CHAR) LEN(298) +
                          VALUE(X'0000012A000100020002000000080008000+
                          0000000000000000000000000000000000000000000+
                          0000000000010000020000000000000000000000000+
                          0180000008C00000015000000000000000000000000+
                          0000000000000000000000000000000000000000000+
                          0000000000000000000000000000000000000000000+
                          0000000000000000000000000000000000000000000+
                          0000000000000000000000000000000000000000000+
                          0000000000000000000000000000000000040000001+
                          8003C00000000000000000000000000000000000000+
                          0000000000000000000000000000000000000000000+
                          0000000000000000000000000000000000000000000+
                          0000000000000000000000000000000000000000000+
                          0000000000000000000000000000000000000000000+
                          00') /* instruction template to compute +
                                  ISO time duration */
             DCL        VAR(&DURATION) TYPE(*DEC) LEN(6 0)

             CALLPRC    PRC('_CTD') PARM((&DURATION *BYREF) +
                          (&EVENING *BYREF) (&MORNING *BYREF) +
                          (&ISODURTMPL *BYREF))

             ENDPGM

Documentation and Examples of System-builtins

IBM's documentation on MI instructions can be found at http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/rzatk/mitoc.htm. Here we document system-builtins for ILE HLLs (MI instructions expose bound program access interfaces HLLs) with plenty of runnable usage examples. System-builtins sorted by topic: