using apis to extend rpg the c runtime apis

Upload: rachmat99

Post on 14-Apr-2018

225 views

Category:

Documents


0 download

TRANSCRIPT

  • 7/30/2019 Using Apis to Extend Rpg the c Runtime Apis

    1/8

    Using APIs to Extend RPG: The C Runtime APIs

    Written by Joe Pluta

    Wednesday, 07 September 2011 00:00 - Last Updated Wednesday, 07 September 2011 00:00

    Many APIs are available on the IBM i that will enable you to extend your RPG

    applications; the C Runtime APIs provide a wide range of added functions.

    In a previous article , I demonstrated how you could use the CEE APIs to provide additional

    programming features to your RPG programs, specifically in the area of advanced mathematical

    and trigonometric functions. The CEE APIs are very standardized, with traditional (for RPG

    programmers, anyway!) parameter- and error-handling. The C Runtime APIs are quite a bitdifferent as they are modeled after the existing APIs of the UNIX world. And while those APIs

    are completely familiar to the UNIX developers among us, we RPG types can use a little help

    getting started with them, and this article provides that help.

    Quick Recap

    You can refer to the other article to see a synopsis of the differences between the CEE APIs

    and the C Runtime APIs. To summarize, the CEE APIs are very standardized and very flexible,

    built to support all kinds of data types and with a fine-grained error-handling framework.Meanwhile, the C Runtime APIs have fewer options, work primarily with floating point numbers

    only, and are all over the board when it comes to naming. The CEE APIs for calculating cosine

    and logarithm are, respectively, CEESDCOS and CEESDLG1. The C Runtime APIs are far less

    structured. For example, the corresponding APIs are cos and log. These seem like simpler

    terms, but others are less intuitive, at least to me (for example, pow is the exponentiation

    function, and it took me awhile to find it).

    One real problem with the C Runtime APIs is that many of them use the standard UNIX names,

    which don't always make it easy to identify which API to use in any given situation. The pow API

    above is one example. There are also about 20 different APIs that deal with time. Functions

    ctime, gmtime, localtime, mktime, and time all return various representations of the current time,

    and each of those have variations. The good news is IBM has some thorough reference

    documentation available. This wasn't the case in the past; you had to sort of know which APIs

    you wanted to use and then you could look up their " man page " (this is the term for the system

    1 / 8

    http://localhost/var/www/apps/conversion/tmp/scratch_9/programming/apis/using-apis-to-extend-rpg-the-cee-apis.htmlhttp://localhost/var/www/apps/conversion/tmp/scratch_9/programming/apis/using-apis-to-extend-rpg-the-cee-apis.htmlhttp://www.manpagez.com/man/3/pow/http://www.manpagez.com/man/3/pow/http://localhost/var/www/apps/conversion/tmp/scratch_9/programming/apis/using-apis-to-extend-rpg-the-cee-apis.htmlhttp://localhost/var/www/apps/conversion/tmp/scratch_9/programming/apis/using-apis-to-extend-rpg-the-cee-apis.html
  • 7/30/2019 Using Apis to Extend Rpg the c Runtime Apis

    2/8

    Using APIs to Extend RPG: The C Runtime APIs

    Written by Joe Pluta

    Wednesday, 07 September 2011 00:00 - Last Updated Wednesday, 07 September 2011 00:00

    documentation for UNIX commands, short for "manual page"). Today better documentation

    exists for these APIs; you can see an exhaustive list in the

    Infocenter

    . The problem with that list is that it's mostly just alphabetical. Another option is to download the

    whole reference inPDF format

    , which I think has a better layout and makes it a little easier to find the APIs you need.

    Making the C Runtime APIs Work for You

    So if the C Runtime APIs have so many potential disadvantages compared to the CEE APIs,

    then why use them? The biggest advantage is that the APIs use return values. Let me just show

    you the difference, and then I'll discuss it in detail. First, the prototypes are simpler. Here are the

    CEE APIs:

    d CEESDLG1 pr extproc('CEESDLG1')

    d input 8F const

    d output 8F

    d error 12 options(*omit)

    d CEESDCOS pr extproc('CEESDCOS')

    2 / 8

    http://publib.boulder.ibm.com/infocenter/iseries/v7r1m0/index.jsp?topic=/apis/hll3.htmhttp://publib.boulder.ibm.com/infocenter/iseries/v7r1m0/topic/rtref/sc415607.pdfhttp://publib.boulder.ibm.com/infocenter/iseries/v7r1m0/topic/rtref/sc415607.pdfhttp://publib.boulder.ibm.com/infocenter/iseries/v7r1m0/index.jsp?topic=/apis/hll3.htm
  • 7/30/2019 Using Apis to Extend Rpg the c Runtime Apis

    3/8

    Using APIs to Extend RPG: The C Runtime APIs

    Written by Joe Pluta

    Wednesday, 07 September 2011 00:00 - Last Updated Wednesday, 07 September 2011 00:00

    d input 8F const

    d output 8F

    d error 12 options(*omit)

    d CEESDXPD pr extproc('CEESDXPD')

    d input1 8F const

    d input2 8F const

    d output 8F

    d error 12 options(*omit)

    And here are the prototypes for the corresponding C Runtime APIs:

    3 / 8

  • 7/30/2019 Using Apis to Extend Rpg the c Runtime Apis

    4/8

    Using APIs to Extend RPG: The C Runtime APIs

    Written by Joe Pluta

    Wednesday, 07 September 2011 00:00 - Last Updated Wednesday, 07 September 2011 00:00

    d log10 pr 8F extproc('log10')

    d input 8F value

    d cos pr 8F extproc('cos')

    d input 8F value

    d pow pr 8F extproc('pow')

    d input1 8F value

    d input2 8F value

    You can see that the C Runtime APIs are simpler. One reason is that error-handling is handled

    internally; the APIs throw exceptions when they encounter errors. Therefore, the prototypes

    have no error-handling parameter. The more important difference is how the results arereturned to the caller: instead of a separate "return value" parameter, the result is defined right

    4 / 8

  • 7/30/2019 Using Apis to Extend Rpg the c Runtime Apis

    5/8

    Using APIs to Extend RPG: The C Runtime APIs

    Written by Joe Pluta

    Wednesday, 07 September 2011 00:00 - Last Updated Wednesday, 07 September 2011 00:00

    on the PR line, indicating that the procedure call itself returns a value. Let's see this in action.

    CEESDCOS( x: cosx: *OMIT);

    CEESDLG1( x: lg1x: *OMIT);

    CEESDXPD( cosx: lg1x: result: *OMIT);

    (versus)

    result = pow( log(x): cos(x));

    The first three lines call the CEE APIs, while the fourth line shows the same calculation using

    the C Runtime APIs. As you can see, the CEE APIs require multiple steps, because each API

    must return its result via a temporary variable. For each step of a complex calculation, you have

    to program the individual steps and then combine those intermediate results using other

    operations. Contrast that with the much more concise version using the C Runtime APIs. Thecalls to log and cos return values. Because of this, the calls themselves can be considered

    5 / 8

  • 7/30/2019 Using Apis to Extend Rpg the c Runtime Apis

    6/8

    Using APIs to Extend RPG: The C Runtime APIs

    Written by Joe Pluta

    Wednesday, 07 September 2011 00:00 - Last Updated Wednesday, 07 September 2011 00:00

    parameters to the pow procedure. That means that you can do the entire

    calculation in one specification.

    This is similar to the way that expressions in RPG IV do away with the need for individual ADD,

    SUB, MULT, and DIV opcodes in RPG III. It is also one of the primary benefits to using

    subprocedures in RPG. You can write your own subprocedures that return values and then use

    those values in more involved computations, making your code simpler and more readable and

    also removing the need for creating temporary variables in your D-specs:

    // Accumulate costs

    TotalCost += quantityRequired * (getCost(thisComponent));

    This single line of code goes and gets the cost for the current component, multiplies it by the

    quantity required, and uses that to increment the total cost. Definitely simpler than the multiplelines of code that would be required in a more traditional RPG program (including the temporary

    values required to hold the cost and the extended cost).

    One thing I haven't mentioned is that using the C Runtime APIs requires a special bindingdirectory, the QC2LE directory. QC2LE is found in QSYS and provides access to the various C

    6 / 8

  • 7/30/2019 Using Apis to Extend Rpg the c Runtime Apis

    7/8

    Using APIs to Extend RPG: The C Runtime APIs

    Written by Joe Pluta

    Wednesday, 07 September 2011 00:00 - Last Updated Wednesday, 07 September 2011 00:00

    Runtime service programs. You include it with a keyword in your H-spec:

    h option( *nodebugio: *srcstmt) bnddir('QC2LE')

    The relevant keyword is bnddir. It tells the compiler to look for the QC2LE binding directory.

    The option keyword is not required to include the C Runtime

    APIs, but I use it on every program and I consider it really important (especially the

    *srcstmt

    option), so I always show it whenever I show an H-spec.

    The Benefits of the C Runtime APIs

    The C Runtime APIs provide an extensive suite of additional functions. Some of the more

    common uses include stream file I/O and string manipulation; RPG simply doesn't support

    stream files that well, and these APIs provide a good way to access the IFS and process the

    data stored there. Another longtime use is searching and sorting; RPG's array processing has

    improved greatly in the past several releases, but the bsearch and qsort APIs are powerful

    alternatives that provide more flexible and fine-grained control over the process.

    The benefits of these APIs extend beyond simply providing some additional functions for RPG,

    however. Learning to use the C Runtime APIs properly will reinforce in your mind the way that

    procedures work and give you a good foundation for coding your own procedures that take

    advantage of the return value concept. And that takes you down the road of ILE and service

    programs, which is a good road to take.

    7 / 8

  • 7/30/2019 Using Apis to Extend Rpg the c Runtime Apis

    8/8

    Using APIs to Extend RPG: The C Runtime APIs

    Written by Joe Pluta

    Wednesday, 07 September 2011 00:00 - Last Updated Wednesday, 07 September 2011 00:00

    So give the C Runtime APIs a whirl and see where they take you.

    as/400, os/400, iseries, system i, i5/os, ibm i, power systems, 6.1, 7.1, V7, V6R1

    8 / 8