using apis to extend rpg the c runtime apis
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