OPM MI Programming Tech-tips

When seeing this page, you may have a couple of questions, "Why programming at the MI level?", and "Why programming OPM MI?".

• The design of TIMI (Techniqual Indepentant Machine Interface) is originated from IBM i's ancestors, and is not available in any other platfroms. We want to let more programmers to know about this design and benefit from it.
• The introduction of the New MI (aka. ILE) programming model allows procedure-oriented programming languages, such as C, be migrated to IBM i and procedure characteristics be added to native IBM i HLLs. ILE is an early-binding programming model which is originated from and widely adopted by common platforms; it's the opposite of the original programming model of IBM i in which program-calls are always dynamic. Obviously, we programmers would have enough oppertunities to learn such techniques with or without the existence of IBM i.

See what we collected here :)

• Exception Management
  • Disable an exception handler
  • Enable an exception handler
  • Retrieve exception data
  • Resignal an exception

Exception Management

This section is about exception management. For detailed description of MI instruction mentioned in this section, please refer to IBM's documentation, Exception Mangement Instructions .

Disable an exception handler

MODEXCPD excpd-name, x'2000', x'01';

Enable an exception handler

MODEXCPD excpd-name, x'A000', x'01';

Retrieve exception data

The Retrieve Exception Data (RETEXCPD) MI instruction can be used to retrieve exception data in an exception handler. Note that the retrieve-option operand (operand 2) should be set to hex 01, 02, and 03 for a branch point exception handler, an internal entry point exception handler, and an external entry point exception handler, respectively.

Imagine the program object II67B called by MI program e009.emi , the exception data of the system object damaged exception (hex 1004) can be retrieved like the following.

/* a damaged program object */
dcl sysptr ii67b auto init (
        "II67B", type(pgm)
)                               ;

        callx ii67b, *, *       ;
brk "CALLPGM"                   ;
see-you:        
        rtx *                   ;

/* exception description */
dcl excm oops excid(h'1000') bp(damage-encountered) imd cv('MCH') ;

/* branch point (BP) exception handler for exception hex 10## */
damage-encountered:

dcl dd len bin(4) auto          ;

        modasa @excp-data-ptr, 8 ;
        cpynv @excp-data?bytes-in, 8    ;
        retexcpd @excp-data-ptr, x'00'  ;
        cpynv len, @excp-data?bytes-out ;

        modasa @excp-data-ptr, -8 ;
        modasa @excp-data-ptr, len ;
        cpynv @excp-data?bytes-in, len ;
        retexcpd @excp-data-ptr, x'00' ;

dcl spcptr excp-data-ptr auto          ;
dcl spc * bas(excp-data-ptr)           ;
        dcl sysptr obj-syp dir         ;
        dcl dd int-dump-id char(8) dir ;
        dcl dd error-class bin(2) dir  ;
        dcl dd dev-num     bin(2) dir  ;

        cmpbla(b) @excp-data?excid, x"1004" / neq(release-asf) ;

        setsppfp excp-data-ptr, @excp-data-ptr ;
        addspp excp-data-ptr, excp-data-ptr, h'30' ;

dcl dd msg char(40) auto        ;
        cpybla msg(1:26), "MCH1604, internal dump ID:" ;
        cpybla msg(28:8), int-dump-id                  ;
        %sendmsg(msg, 40)                              ;

release-asf:    
        neg(s) len                ;
        modasa @excp-data-ptr, len ;
        b see-you               ;

/* Exception data template for RETEXCPD and SIGEXCP */
dcl spcptr @excp-data-ptr auto   ;
dcl spc @excp-data-t bas(@excp-data-ptr) ;
        dcl dd @excp-data?bytes-in       bin(4) dir ;
        dcl dd @excp-data?bytes-out      bin(4) dir ;
        dcl dd @excp-data?excid          char(2) dir ;
        dcl dd @excp-data?cv-len         bin(2) dir  ;
        dcl dd @excp-data?cv             char(32) dir ;
        dcl dd @excp-data?msg-ref-key    char(4) dir  ;
        /* offset = h'30' */
        /* exception specific data */

pend                            ;

Resignal an exception

A robust program should always be aware of exceptions. Also, it should report exceptions that it cannot handle as soon as possible. This is a design consideration for transparency.