i5/OS Programmer's Toolkit: EMI (Extended i5/OS Machine Interface Language) and MIC (MI/EMI Compiler)

0.2.16

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

Translations of the current page:

Chinese: i5/OS Programmer's Toolkit: EMI (扩展i5/OS机器接口语言) 和 MIC (MI/EMI编译器)

MI (i5/OS Machine Interface) is a logical layer between i5/OS applications and the Licensed Internal Code (LIC) layer. The MI has two variats that share many common characteristics but take different approaches: the original MI (OMI) and the new MI (NMI). Here the term MI we refer to is the OMI.

What EMI (Extended i5/OS Machine Interface Language) is, and what EMI is not

is a language extension to i5/OS Machine Interface Language
EMI extends MI language with compiler directives and an extensible builtin library; EMI is designed to enhance MI code's resusability and promote MI programmer's coding efficiency without impacting the flexibility of MI language.

is NOT a new language on i5/OS
EMI is NOT a fresh new language on i5/OS. All EMI codes are converted to MI codes that can be recognized by the OMI compiler (the QPRCRTPG API), and finish compilation steps by invoking the OMI compiler.

is a convient way for system programmers to understand the sophisticated OS and at the same time improve their productivity in MI programming wiht less lines of codes and more readability.

Contents

Download and Install MIC

MIC is a sub-project of project i5/OS Programmer's Toolkit . All releases of i5/OS Programmer's Toolkit can be found here

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

To install MIC please refer to the readme file in the downloaded release package.

EMI's Hello World!

Assume that we have two EMI source files, respectively stored in an IFS stream file (*STMF) /home/ljl/tmp/hello.emi, and a source physical file (PF) member SRCLIB/MISRC(WORLD). Program HELLO calls program WORLD to get the name of a programming language randomly, then generate an informational message, 'Hello + language-name' using EMI builtin %sendmsg.

*STMF source file /home/ljl/tmp/hello.emi

entry hello-main ext            ;

dcl sysptr pgm-world auto init("WORLD", type(pgm)) ;
dcl dd msg char(32) auto                           ;
dcl dd len bin(4) auto                             ;
dcl spcptr msg-ptr auto init(msg)                  ;
dcl ol argl-world(msg-ptr) arg                     ;

brk 'INIT'                             ;
        cpyblap msg, 'Hello, ', ' '    ;
        addspp msg-ptr, msg-ptr, 7     ;
        callx pgm-world, argl-world, * ;

brk 'SEND_MSG'                  ;
        triml len, msg, ' '     ;
        %sendmsg(msg, len)      ;

brk 'END'                       ;
        rtx *                   ;
pend;
/* eof - hello.mi */

Database file system source SRCLIB/MISRC(WORLD)

dcl spcptr .world parm           ;
dcl ol pl-world(.world) parm ext ;
entry * ext                     ;

dcl dd world char(8) bas(.world) ;
dcl dd words(0:3) char(8) init(
        *(0)'ILE RPG',
        'COBOL',
        'Java',
        'MI'
) ;

dcl dd buf char(8) auto         ;
dcl dd i bin(2) unsgnd def(buf) pos(7) ;

        matmdata buf, x'0000'   ;
        div(s) i, 16384         ;
        cpyblap world, words(i), ' ' ;
brk 'END'                       ;
        rtx *                   ;
pend;
/* eof - world.mi */

Compile program objects

Compile program HELLO from *STMF source file /home/ljl/tmp/hello.emi by QShell command mic

     qsh
     > cd /home/ljl/tmp
     > mic -q*replace hello.emi             
       mic:  -- program HELLO      is placed in library LSBIN

Compile program WORLD from database source SRCLIB/MISRC(WORLD) by CL command MIC

     > MIC PGM(WORLD)
           SRCPATH('/qsys.lib/srclib.lib/misrc.file/world.mbr')
           OPTION(*REPLACE)   /* replace existing program with the same name */
       mic:  -- program WORLD      is placed in library LSBIN.

Now, run program HELLO under CL environment

    > CALL PGM(HELLO)
      Hello, COBOL   
    > CALL PGM(HELLO)
      Hello, MI      
    > CALL PGM(HELLO)
      Hello, ILE RPG 
    > CALL PGM(HELLO)
      Hello, ILE RPG

Command Interface of MIC

MIC can be invoked either from CL environment or within a QShell session.

CL Command MIC

MIC's CL command is I5TOOLKIT/MIC. Make sure you have involved library I5TOOLKIT into your library list before invoking CL command MIC.

Description of command parameters of CL command MIC.

Parameter Name Description

Program (PGM) Library and name of created program object; the library name is default to *CURLIB

Source path name (SRCPATH) Source path name. See Comment 1, Comment2

Text description (TEXT) Text description of created program object

Output printer file (OUTPUT) Printer file name used to generate compiler listing; default to *LIBL/QSYSPRT. See Commnent 3

Public authority (AUT) Public authority; default to *ALL

Include directories (INCDIR) Include directories, up to 15; can be absolute path names or relative path names in stream file systems or the database file system in IFS (Integrated File System) path name format. See Comment 1.

Compiler options (OPTION) Compiler options, see Machine interface language syantax provided by IBM, Create Program (QPRCRTPG) API

Comment 1. MIC supports either stream source file and database file system source. When refer to a stream source file, specifiy the IFS path name of the stream source file for parameter SRCPATH. For example, /home/ljl/misrc/hello.emi. When refer to a database file system source, specify the path name in '/qsys.lib' format for paramter SRCPATH. For example, /qsys.lib/srclib.lib/misrc.file/world.emi. Note that when using database file system source on i5/OS, we can only store sources in source physical file. When applying DSPFD (Display File Description) command on a source physical file, the 'File type (FILETYPE)' attribute is '*SRC', while a data physical file's file type attribute is '*DATA'.

Comment 2. MIC supports either absolute path name or relative path name when locating a source file. Combining relative path name with a job's current working directory setting will befinit programmers a lot when specifying target source file path or paths of include directories. When working under QShell environment, the current working directory is always the place where we are. When working under CL environment, one can change his current working directory by CL commands CHDIR or CHGCURDIR, and view his current working directory setting by CL command DSPCURDIR.

Comment 3. To make MIC output compiler listing information, specify the *LIST option in CL command MIC's parameter OPTION. The compiler listing will be output to a spooled file with the name set to the printer file name specified in parameter OUTPUT.

QShell Command mic

MIC's QShell interface is QShell command /usr/bin/mic. Run mic with option -h to show a brief help message.

> mic -h                                          
  Usage: mic [options] source-file-name
  Options:                                        
          -v      Verbose
          -V      Show version information
          -h      Show help information           
          -o      Name of created program object
          -t      Text description                
          -l      Output printer file name        
          -a      Public authority                
          -I      Include path                    
          -q      Compiler options
          -L      Library name of created program object
                                                  
  Report bugs to junleili-cn@users.sourceforge.net

Command options of QShell command mic

Option name Description

-h Show help information

-v verbose, when specifying -q*list option, output compiler listing

-V Show version information

-o program-name Created program name; default to source file name

-t text Text description of created program

-l printer-file Printer file name used to generate compiler listing; default to *LIBL/QSYSPTR.

-a public-authority Public authority; default to *ALL

-I include-path Include directories, up to 15; can be absolute path names or relative path names of IFS or database file system.

-q compiler-option Compiler options, see Machine interface language syantax provided by IBM Create Program (QPRCRTPG) API

-L library-name Library name of created program object. If environment variable OUTPUTDIR is set, use the value of the OUTPUTDIR. If environment variable OUTPUTDIR is not set, use job's current library.

Remarks:: If no source-file-name is specified, MIC reads source code from the standard input. When reading source code from stdin, if -o option does not present MIC uses a.out as the name of the created program object.

Usage Example of MIC Commands

For more MIC usage examples, please refer to Best Practices in Using MIC.

Use relative path name for target source file or include directories
Assume that we have a database file system source file member, SRCLIB/MISRC(HELLO) which include another database file system source file member, SRCLIB/MISRC(UTIL_INC). To compile program HELLO, we might issue the following CL command

> CHGCURDIR DIR('/qsys.lib/srclib.lib/misrc.file') /* change job's current working directory */
  Current directory changed.                                               
> MIC PGM(HELLO)
      SRCPATH(hello.mbr)  /* specify relative path name */
      TEXT('using relative path name')
  mic:  -- program HELLO      is placed in library *CURLIB.

In the example showed above, both target source member hello.mbr and included source member util_inc.mbr are located under the current working directory, /qsys.lib/srclib.lib/misrc.file.

Use database file system source and *STMF source at the same time
Assume that our target source file is a database source file member, SRCLIB/MISRC(HELLO). Source files included by SRCLIB/MISRC(HELLO) are placed under IFS directories /home/ljl/mi-inc and /home/ljl/mi-inc/sub-dir respectively. To compile program HELLO, we might issue the following CL command

> CHDIR DIR('/home/ljl/mi-src')
  Current directory changed.   
> MIC PGM(HELLO)
      SRCPATH('/qsys.lib/srclib.lib/misrc.file/hello.mbr')
      INCDIR('sub-dir')
      OPTION(*REPLACE)                                            
  mic:  -- program HELLO      is placed in library *CURLIB.

Output compiler listing when compiling from QShell
To output compiler listing under QShell environment, -v option and -q*list option must be specified at the same time. For example

qsh
> mic -v -q*replace -q*list hello.emi

Input source code from the standard input when invoking mic under QShell Environment

When invoked under QShell Environment without the source-file-name option, MIC reads source code from the stdin. If -o option is not specified, MIC uses a.out as the name of the created program object.

> mic << eof
  >
> entry * ext;
  >
> dcl dd msg char(32) auto init('happy birthday:)');
  >
> dcl dd len bin(2) auto;
  >
>     triml len, msg, ' ';
  >
>     %sendmsg(msg, len);
  >
>     rtx *;
  >
> pend;
  >
> eof
  mic:  -- program A.OUT      is placed in library LSBIN
  $
> system "call a.out" # run program A.OUT
         :
  happy birthday:)
  $

EMI Syntax Specification

EMIs support Machine interface language syantax which is described in Create Program (QPRCRTPG) API's documenation. Additionally, EMI provides language extensions to traditional MI syntax.

Difference between MIC syntax and traditional MI syntax
- EMI ignores cases of all symbol in source code. All symbol except character constants are converted UPPER case internally.
- You should avoid names in your source code that starts with '@' or '.@'. Since names used by EMI builtins start with '@' or '.@'.

For EMI compiler directives, see EMI Compiler Directives.

For reference on EMI builtins, see Specifications of EMI Builtins.

Other limits
- EMI supports single-line or multi-line comments. A comment starts with character sequence '/','*', and end with character sequence '*','/'. EMI does NOT support nested comments. For example
```
     /* single-line comment */
     /*
 multi-line comment

 ... ...
      */
```
- EMI supports up to 15 levels of nested source includes, deeper includes will be ignored. So one should pay attention to the depth of including, and avoid recursive includes. For example, including a source file itself directly or indirectly.

MIC Conventions

Compiler Include Directories

MIC searches the following directories for compiler includes

Remarks:: The compiler include directories are placed at the end of search path list when locating an include file. So it is possible to override a compiler supplied include file with a user supplied one.

Contact us

If you have any advice on EMI/MIC or other sub-project of i5/OS Programmer's Toolkit, please contact us through

our email: junleili-cn@users.sourceforge.net
open discussion forum of the project: https://sourceforge.net/forum/forum.php?forum_id=922956

About the Author

Hi, I'm Junlei Li (李君磊) from Tianjin, China. I'm a "young" AS/400 programmer who started programming under this platform since late 2005. This OS has been my best tutor through these years. Many thanks to people who had brought this excellent OS to the world with so many designs ahead of the times even today.

In my open source project i5/OS Programmer's Toolkit, more than a half of the source code is written in MI. I have to appreciate Mr. Leif Svalgaard for his excellent articles about MI programming in the MI-400 list at midrange.com.

Other helpful web sites for me include:

I'm available at junleili-cn@users.sourceforge.net. Any comments and suggestions are always welcome :)

Parameter Name	Description
Program (PGM)	Library and name of created program object; the library name is default to *CURLIB
Source path name (SRCPATH)	Source path name. See Comment 1, Comment2
Text description (TEXT)	Text description of created program object
Output printer file (OUTPUT)	Printer file name used to generate compiler listing; default to *LIBL/QSYSPRT. See Commnent 3
Public authority (AUT)	Public authority; default to *ALL
Include directories (INCDIR)	Include directories, up to 15; can be absolute path names or relative path names in stream file systems or the database file system in IFS (Integrated File System) path name format. See Comment 1.
Compiler options (OPTION)	Compiler options, see Machine interface language syantax provided by IBM, Create Program (QPRCRTPG) API
Comment 1.	MIC supports either stream source file and database file system source. When refer to a stream source file, specifiy the IFS path name of the stream source file for parameter SRCPATH. For example, /home/ljl/misrc/hello.emi. When refer to a database file system source, specify the path name in '/qsys.lib' format for paramter SRCPATH. For example, /qsys.lib/srclib.lib/misrc.file/world.emi. Note that when using database file system source on i5/OS, we can only store sources in source physical file. When applying DSPFD (Display File Description) command on a source physical file, the 'File type (FILETYPE)' attribute is 'SRC', while a data physical file's file type attribute is 'DATA'.
Comment 2.	MIC supports either absolute path name or relative path name when locating a source file. Combining relative path name with a job's current working directory setting will befinit programmers a lot when specifying target source file path or paths of include directories. When working under QShell environment, the current working directory is always the place where we are. When working under CL environment, one can change his current working directory by CL commands CHDIR or CHGCURDIR, and view his current working directory setting by CL command DSPCURDIR.
Comment 3.	To make MIC output compiler listing information, specify the *LIST option in CL command MIC's parameter OPTION. The compiler listing will be output to a spooled file with the name set to the printer file name specified in parameter OUTPUT.

Option name	Description
-h	Show help information
-v	verbose, when specifying -q*list option, output compiler listing
-V	Show version information
-o program-name	Created program name; default to source file name
-t text	Text description of created program
-l printer-file	Printer file name used to generate compiler listing; default to *LIBL/QSYSPTR.
-a public-authority	Public authority; default to *ALL
-I include-path	Include directories, up to 15; can be absolute path names or relative path names of IFS or database file system.
-q compiler-option	Compiler options, see Machine interface language syantax provided by IBM Create Program (QPRCRTPG) API
-L library-name	Library name of created program object. If environment variable OUTPUTDIR is set, use the value of the OUTPUTDIR. If environment variable OUTPUTDIR is not set, use job's current library.