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 bit different 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 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 in PDF 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')

     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:

     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 are returned to the caller: instead of a separate "return value" parameter, the result is defined right 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. The calls to log and cos return values. Because of this, the calls themselves can be considered 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 multiple lines 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 binding directory, the QC2LE directory. QC2LE is found in QSYS and provides access to the various C 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.

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