IBM i > DEVELOPER > RPG

Utilizing MI Functions in RPG Programs


 

Sponsors:
Advanced Systems Concepts: Top Ten Reasons why you should Retire Query/400/
BOSaNOVA: Leverage your present investment in Twinax displays and printers and move seamlessly forward to a single network protocol with the award-winning e-Twin@x Controller from 14-year industry veteran Better On-Line Solutions.
COMMON:

Attend COMMON's IT Education Conference & Expo, October 17-21, in Toronto, ON, Canada.  Choose from many sessions and labs including an EAM (Enterprise Application Modernization) focus.  Registration is $1,295 before 09/23/04. The COMMON IT Executive Conference will also be held in Toronto, October 17-19.

Stalker Software:CommuniGate Pro - Advanced Messaging with Groupware. Integrated  E-mail & Collaboration solution; Supports over 30 platforms; Outlook(R) & Web support for e-mail, calendaring, group scheduling, shared folders, tasks, contacts, and more.

Trailblazer Systems: Connecting to UCCnet? TrailBlazer Systems has an iSeries solution that links your ERP system directly to UCCnet. Using ZMOD Exchange UCCnet, information is validated, formatted, and automatically posted to UCCnet.

One of the most frequently asked questions to appear on RPG Internet lists is, "How can I convert a character string to its hex equivalent?" Wed like to answer this popular question by introducing you to the wonderful world of utilizing machine interface (MI) functions in RPG programs. Hopefully most of you have heard of MI, even if youre not quite sure what its all about.

In the simplest of terms, MI is the closest thing there is to a native assembler language on the iSeries platform. In the "olden days" of RPG/400 and the other OPM compilers, MI was the intermediate language that the compilers generated from our RPG and COBOL programs. The resulting MI was then translated into the raw machine instructions that were actually executed. Current ILE compilers dont generate MI, but W-code. Because IBM doesnt make the details of W-code available, MI remains our only access to some of the systems lower level functionality.

Most, but not all, MI instructions are "surfaced" for use in one or both of two forms: C functions and built-ins. A list of all of the supported MI functions is available in the Appendix "Reference Summary" of the ILE C/C++ for AS/400 MI Library Reference.

(Note: To see an example of the generated code, compile an old RPG/400 program specifying the additional option GENOPT(*LIST). Now take a look at the spool file, and youll see the generated MI code. You can learn a lot about MI just by studying the compiler listings, but if you really want to get into the nuts and bolts of MI programming, then theres only one place to go: Leif Svalgaarrds web site, which offers a complete MI tutorial and many sample programs. The full tutorial is a fee-based offering, but Leif does allow you to download his COMMON presentation handout and other sample pages. Another resource is IBMs MI functional reference manual, but this has few examples and cannot be downloaded.)

Now that weve laid the groundwork, lets get to the task at hand. Well be using the MI instruction CVTHC to convert a string to hex. Given the "ABC" character string, the instruction produces a string containing the "C1C2C3" hex representation. CVTHC is surfaced as the C function "cvthc", so thats the actual version well be using. Because requests for the reverse operation (converting a hex string to its character equivalent) are almost as frequent, our simple program also demonstrates the MI instruction CVTCH (C function "cvtch").

(A)  H DftActGrp(*No) BndDir('QC2LE')

(B)  D ToHex           PR                  EXTPROC('cvthc')
(C)  D  HexResult                 65534A   OPTIONS(*VARSIZE)
(C)  D  CharInp                   32767A   OPTIONS(*VARSIZE)
(C)  D  CharNibbles                  10I 0 VALUE

     D FromHex         PR                  EXTPROC('cvtch')
     D  CharResult                32767A   OPTIONS(*VARSIZE)
     D  HexInp                    65534A   OPTIONS(*VARSIZE)
     D  HexLen                       10I 0 VALUE

     D TestString      S             26A   Inz('Jon and Susan +
     D                                           - Partner400')
     D HexEquivalent   S             52A
     D Result          S             26A

     C     TestString    Dsply

(D)  C                   CallP     ToHex(HexEquivalent:
     C                                TestString: %Len(TestString) * 2)

(E)  C     HexEquivalent Dsply

     C                   CallP     FromHex(Result:
     C                              HexEquivalent: %Len(HexEquivalent))

     C     Result        Dsply

     C                   Eval      *InLR = *On

(A) The first thing to note in the sample program is the use of the H spec entry BNDDIR("QC2LE"). This directory is shipped with the system for the benefit of the C compiler. Because we want to access routines normally associated with C programs, we inform the RPG compiler to add it to its search list.

The prototype for "cvthc" is shown at (B). Weve named it "ToHex" because the original name gives the impression that it converts from hex to character rather than the other way around. (And yes, weve made that mistake.)

The procedure takes three parameters (C). The first is the result field; this is where the converted hex string will be placed. The second is the input character string, and the third is the length of that input field in nibbles (i.e., the number of bytes * 2). Why the routine couldnt accept the length of the character field and multiply it by 2 itself is anyones guess.

 

Jon Paris is a technical editor with IBM Systems Magazine and co-owner of Partner400.

Susan Gantner is a technical editor with IBM Systems Magazine and co-owner of Partner400.


comments powered by Disqus

Advertisement

Advertisement

2018 Solutions Edition

A Comprehensive Online Buyer's Guide to Solutions, Services and Education.

New and Improved XML-INTO

Namespace support makes the opcode a viable option

Authenticating on the Web

The finer points of OpenRPGUI, Part 1

The Microphone is Open

Add your voice: Should IBM i include open-source RPG tools?

IBM Systems Magazine Subscribe Box Read Now Link Subscribe Now Link iPad App Google Play Store
IBMi News Sign Up Today! Past News Letters