1. Introduction
    1. Why Program at the Machine-Level?
    2. Leaving aside the precise definition of Machine-Level for a bit, a good reason is that it is just plain olí fun. It certainly is different from cranking out RPG-programs. Then there are all the standard reasons that have to do with wringing more performance out of your system with the usual caveats about only optimizing what is worth optimizing. There are many APIs on the AS/400 that are just machine-level instructions in disguise, and at times bad ones at that. When you are using such an API, you are doing machine-level programming, but often without understanding precisely what is going on and often forced into a clumsy and tedious format required by the high-level language you are using. If you know how to program at the machine-level, you will find it easier to use APIs from your high-level language, and will use them with more confidence. Finally, there are things that you just canít do in any reasonable, other way without going to the machine-level.

    3. What is the Machine-Level?
    4. One definition is that it simply is the lowest level at which you can work as a programmer. This level constitutes an abstract machine, and you program to that abstraction. There are always levels below that you ordinarily donít care about, and in fact often donít want even to know about. The AS/400 is somewhat unusual because there are two machine-levels that play a role in practice. The upper one is called the MI-level and the lower one is the CISC/RISC platform. MI, or the Machine Interface, is in a very real sense what makes your machine an AS/400 rather than just a souped-up PowerPC. This book will show you how to program to the MI-level. We shall also examine the RISC platform in detail so you will understand something of what goes on "under the covers".

    5. Above and Below the MI
    6. The operating system that controls your machine has two parts. Over time some misleading nomenclature has been used. You have probably heard about "horizontal" and "vertical" micro-code. These names have fallen out of favor, mainly for legal reasons. Since "micro-code" is considered part of the hardware you can own micro-code. IBM doesnít want you to own the operating system, so requires you to license it instead, hence had to change the names. Today, names like OS/400 and SLIC (System Licensed Internal Code) are used. Basically, OS/400 is programmed to the MI-level and SLIC is programmed to the PowerPC RISC platform. This is often expressed by saying that OS/400 (and your applications) are above the MI and SLIC is below the MI, hence justifying talking about the machine interface.

    7. Old MI and New MI
    8. Just as the AS/400 hardware has evolved, MI has too. MI was designed to be extensible and new operations and functionality have been added over time as needed. We are at a point now where one can talk about the "old" or classic MI supporting the "old programming model", OPM, and the "new" MI supporting the ILE programming model with its emphasis on C-style programs. Todayís RISC-based AS/400 only support the ILE programming model, but a special module in SLIC takes care of transforming OPM program objects into ILE modules bound into an ILE program. The module that does that has been called the "Magic" module. There is this notion that there is some magic involved in MI-programming. I donít like magic. There is a famous quote from the Science Fiction master Arthur C. Clarke that "any sufficiently advanced technology is indistinguishable from magic". One purpose of this book is to dispel some of the magic by seeking an actual understanding of what is happening.

    9. Is MI Hard and Arcane?
    10. It is a common misconception that machine-level programming is hard. There may be some truth to that at the RISC level, but that certainly is not so at the MI-level. MI is a very expressive language with powerful data structuring facilities that makes programming easy and straightforward. I can still remember my very first MI-program (some time back in 1989). I converted a 2000-line COBOL program into MI in less than a week and it ran the first time dropping the time it took to generate a 5250 datastream from 0.337 seconds to 0.017 seconds for a speed-up factor of 20. If I can do it, so can you.

    11. What About All Those MI-Instructions?
    12. Analysis of several large production-type MI-programs containing thousands of instructions show that only 10 instructions comprise almost 80% of all instructions used:

      Mnemonic Freq % of Total Instruction Description

      CPYBLA 19.89 % 19.89 % Copy Bytes Left Adjusted

      CPYNV 10.86 % 30.75 % Copy Numeric Value

      B 10.03 % 40.78 % Branch

      CMPNV 9.79 % 50.57 % Compare Numeric value

      ADDN 7.95 % 58.52 % Add Numeric

      CMPBLA 6.53 % 65.05 % Compare Bytes Left Adjusted

      CPYBLAP 4.27 % 69.32 % Copy Bytes Left Adjusted with Pad

      CALLX 3.80 % 73.12 % Call External (program)

      SUBN 3.62 % 76.74 % Subtract Numeric

      CALLI 2.67 % 79.41 % Call Internal (subroutine)

      Fundamental operations include copying characters (CPYBLA and CPYBLAP), copying numbers (CPYNV), branching (B), and comparisons (CMPBLA for characters and CMPNV for numbers). These alone make up more than 61% of all instructions coded. The moral of this exercise was to show that a lot could be accomplished with a little, so you should be able to quickly become productive. Ovid said "Add little to little and there will be a big pile", same thing here.

    13. Small Programs or Large Programs
    14. Some people advocate only writing very small programs in MI. Useful programs can be as short as a single instruction (with an implied return instruction). The argument is that maintaining MI programs is hard. This is actually not the case, rather, well-written MI-programs are easy to maintain (as are most well-written programs in any language). What was true, was that finding people with the skills needed was hard. That is another one of the reasons for this very book. When you have worked your way through the book, you will find that acquiring MI-skills was not all that hard.

      I know of whole applications written solely in MI, comprising tens of thousands of lines of source code. Experience shows that these applications are not any harder to maintain than applications written in other languages. Because of the interoperability of programs on the AS/400 (one of the delivered promises of ILE) it probably would make good sense to write pieces of the application in languages best suited for that particular piece, with MI taking its place among the others on an equal footing doing what it does best.

    15. Why is MI so Secret?

As we all know, IBM has not been very helpful in supplying information about MI-programming. The hoped for support, expressed in NEWS 3X/400 September 1989, that "You may decide that you would like IBM to let the S/38 and AS/400 "be all that they can be" by openly supporting MI" did not come to pass. There have been a handful of articles in the various AS/400 publications, and only recently has there been a mailing list (MI400@MIDRANGE.COM) to cater for the curious-minded AS/400 programmers. The IBM public documentation for the MI language is vary sparse. The MI Functional Reference Manual, which describes each (of a subset, only) MI instruction doesnít even have one single MI example within itís many pages. The System API Reference manual has a tiny chapter, dedicated to the MI language syntax, but all of this information not really enough to be a working set of reference materials for programming in MI. Maybe this book will help you to make the AS/400 "be all that it can be"?