Support This Project Get i5/OS Programmer's Toolkit at SourceForge.net. Fast, secure and Free Open Source software downloads

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:

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

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

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.

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.

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.

Related Readings and Links

Contact us

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

About the Author

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 :)


Support This Project
Generated on Mon Aug 1 22:50:22 2011 for i5/OS Programmer's Toolkit: MIC - The Machine Instruction Language Compiler by  doxygen 1.5.9