RPG is a fantastic language for business calculations, but sometimes it needs a little help with the more esoteric computations, and that's where APIs come in.

I recently had an opportunity to program some electrical formulas (or do you say formulae?). This took me out of my normal comfort zone of traditional business mathematics and made me hearken back to my days of algebra and trigonometry. While I couldn't have done this in RPG III, it is possible in RPG IV—even using the traditional fixed-format technique. And if you're willing to stretch a bit and use ILE concepts, it's actually quite easy to do arbitrarily complex mathematical calculations in RPG IV and especially in free-format RPG. All you need is a good set of mathematical APIs, and as it turns out, the IBM i provides you with not one, but two distinct sets of APIs that can be used for the purpose: the CEE APIs and the C Runtime APIs. This article will cover the CEE APIs, and I'll follow up with the C Runtime APIs in a second article.

Why Two Sets of APIs?

I don't know the definitive answer to that question, but I can tell you the primary difference between the two and the real-world implications. CEE APIs use bidirectional parameters. They are more like traditional called programs in the sense that the calling program uses a parameter list with some input and some output parameters. The input parameters are used in the computation, and the result is returned via the output parameters. Let's take the example of calculating a logarithm. You would need one input parameter and one output parameter. The input parameter would be the number for which you need the logarithm (say, 100), and the output parameter would return the logarithm of 100 (which would be 2).

The C Runtime APIs work a bit differently. They are ILE procedures and expect one or more input parameters (basically the same parameters as the corresponding CEE APIs), but they return the result as the return value of the procedure. This is a more natural technique for non-RPG programmers; it's the style used in C programming, which is where the C Runtime APIs come from. The QC2LE binding directory includes service programs that expose various C APIs available on the IBM i. So that means that unless you're comfortable with ILE, you won't be using the C Runtime APIs. But I'll cover that aspect in more detail in the follow-up article.

Today's Lesson: The CEE APIs

Today I'll demonstrate the CEE APIs. Let me start with a simple exercise. I want to compute an arbitrary value: I want to raise the cosine of a value to the power of its log. That is, I want to compute cos(x) to the log(x) power. This particular equation is not likely to be something you would see in the real world, but it will illustrate the main points of the CEE APIs. In order to execute this equation, in addition to some standard prototypes, I need just a few lines of code. Let me get the prototypes out of the way first:

     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)

The prototypes are very similar. All start with CEES, all take two or three floating point parameters, and all have an error parameter with options(*omit) specified. You may have noticed that all of these APIs start with CEESD; the D happens to denote the type of the parameter. The CEE APIs are very flexible in that versions exist for various data types, typically integer and floating point of both single and double precision as appropriate (for example, floating point numbers aren't supported when calculating factorials). You can see which APIs are available for which data types here. The CEE APIs even have a set of functions for performing complex math functions on imaginary numbers. It is very easy to switch between the various data types: change CEESDLG1 to CEESSLG1, and you can now pass in single-precision floating point numbers (type 4F in RPG) instead of double-precision.

This flexibility also extends to error handling. You can either test for various error conditions using the error feedback area or you can omit that parameter. If you omit the parameter (and this means using the *OMIT keyword on the call as opposed to not passing the parameter at all), then any error conditions (divide by zero, overflow, etc.) will generate an exception message. You can see the exceptions here.

Now that we have a basic introduction to the CEE APIs, let's take a look at the actual code. It's quite straightforward. First, define the work variables.

     d x               s              8F

     d result          s              8F

     d cosx            s              8F

     d lg1x            s              8F

Then, use either fixed-format or free-form RPG calculations to call the APIs:

     c                   callp     CEESDCOS( x: cosx: *OMIT)

     c                   callp     CEESDLG1( x: lg1x: *OMIT)

     c                   callp     CEESDXPD( cosx: lg1x: result: *OMIT)

(or)

       CEESDCOS( x: cosx: *OMIT);

       CEESDLG1( x: lg1x: *OMIT);

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

Note that I need to define four variables in total. The variables x and result are of course the beginning and ending values, but cosx and lg1x are the intermediate values needed to execute the computation. Since each CEE API must return its value in a bidirectional output parameter, this is the best that you're going to be able to do (unless you further wrap each CEE API in your own procedure). But the calls are simple, and because I'm omitting the error parameter, the code is very clean. The downside of omitting the error feedback parameter is that any bad data will raise an exception, but I'll leave error checking to you.

Deciding When to Use the CEE APIs

So how do you decide between the CEE APIs and the C Runtime APIs? Well, a lot depends on what the program is supposed to do. The CEE APIs provide a lot more than mathematical functions. You can see the categories in the Infocenter. In addition to the mathematical functions, the APIs include condition handling (including the indispensable CEEHDLR API), activation group control, program handling, and storage management, among others. If you find yourself already using some of these APIs, then you may want to also use CEE APIs for mathematical functions for consistency. The CEE APIs also provide a finer-grained control over your exception handling.

If, on the other hand, your program is entirely mathematical in nature and you want to be able to write really simple and readable code, you might want to consider the C Runtime APIs. Thanks to the way those APIs are designed, you can use them to write the same code like this:

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

I'll show you how that works in the follow-up article.

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