Using Apis To Extend RPG The C Runtime Apis

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 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
1/8

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')
2/8

d input 8F const
d output 8F
d CEESDXPD pr extproc('CEESDXPD')
d input1 8F const
d input2 8F const
d output 8F
And here are the prototypes for the corresponding C Runtime APIs:
3/8

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
4/8

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
5/8

parameters to the calculation in one specification.
pow procedure. That means that you can do the entire
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
6/8

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

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

Using Apis To Extend RPG The C Runtime Apis

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Using Apis To Extend RPG The C Runtime Apis

Uploaded by

Copyright:

Available Formats

Using APIs to Extend RPG: The C Runtime APIs