If you're like most AS/400 programmers, you probably haven't experimented with APIs very often. It's probably not your fault. The day-to-day responsibilities of your job may never call for the functionality provided by APIs. But there are hundreds of these little creatures out there for your use, so you may want to research them, because it's quite possible you've already written something that could have been accomplished easier and more efficiently with the use of an API. Come check one out with me.

Case in point: A colleague of mine asked if I had any RPG code that generated random numbers. I told him that I didn't, but that I would help him write one if he wanted me to. He said there was no need to do that because he was already in the process of writing one, but thought he would ask me first, just in case I had already done it. The next day, I looked up system APIs under IBM's Information Center, and, sure enough, I found it: the random number generator CEERAN0.

Searching for an API to accomplish a programming task can be a very worthwhile exercise, and as IBM adds more and more APIs to the system (just wait until V5R2), doing so might pay off even more. So now that you understand you should get to know your iSeries APIs, let's get into some details.

Most of the APIs out there are not ILE-capable, meaning that the only way that you can call them is by external, dynamic calls. You can prototype a non-ILE API using the EXTPGM keyword on the prototype, but OS/400 will still call the program using a dynamic, external call, just as if you'd used the CALL operation in RPG. The reason some programmers prototype non-ILE APIs is that doing so has many advantages, such as compile-time parameter checking, consistency in calling programs (a good idea if you are a heavy ILE shop), promoting code reuse, or simply providing the system API with a more user- and programmer-friendly name that will be referenced throughout the application.

But, alas, there are ILE-capable APIs, and they all start with CEE. These APIs allow those in a pure ILE environment to remain that way, even when calling APIs. The CEE APIs are procedures and as such allow you to statically bind to them and call them using prototype or bound calls. All CEE APIs contain an optional feedback condition code parameter that can be used to return a severity code and a CEE message identifier to the calling program or procedure, which then can be used in an ILE condition handler to percolate the message to the user. I will cover condition handlers in a future article, so for now know that they exist and CEE APIs can be used with them.

Another advantage of ILE APIs is that they can use operational descriptors, which is an ILE-only feature. Some CEE APIs require additional information about the data being passed to it. Operational descriptors provide that extra information. They don't require the calling program or procedure to code anything extra about the parameters or add additional parameters to deal with the operational descriptors. All that is necessary if a procedure requires operational descriptors is to code the keyword OPDESC in the prototype of the procedure or API. If you are using a bound call instead of a prototyped call, you can still pass operational descriptors with the D extender, like so:

CEEDATAM is an API that converts seconds to a time stamp and, in fact, does require operational descriptors to tell it a little more about the variable length strings parameters it accepts. OK, now that you understand a little about the ILE CEE APIs, let's get back to the specific API you joined me to read about.

I have included a little program, GetRandom, and the source code for the CEERAN0 prototype, GetRandomP. First take a look at the prototype.

It's pretty simple. I decided not to use the CEERAN0 name throughout my application, so I renamed it GetRandomNum and referenced the CEERAN0 API, using the EXTPRC keyword on the prototype line. Notice I used EXTPRC and not EXTPGM. EXTPRC says that I am referencing an ILE procedure; whereas EXTPGM states that I am referencing a program. The latter cannot be statically bound and, therefore, cannot be statically called.

The first parameter is called the seed. The API will use this parameter as a base for the random number generator. For example, by passing a zero (0) in this parameter, the API will generate the random number using Greenwich Mean Time. This parameter must be passed by reference because the CEERAN0 will change the seed so that you can use that seed for the next call to the API. Sort of a random number to generate the random number, if you will.

The second parameter is the actual random number. It is represented by an 8-byte floating-point number and ranges between zero (0) and one (1) exclusively.

The third parameter is the feedback condition data I mentioned earlier. It is an optional parameter, so I defined it as such by coding the *OMIT option. There are no operational descriptors required by this API, so I did not include the OPDESC keyword in the prototype definition.

Now let's take a look at the program that calls the API. Again, it's pretty basic. The first thing I do is to add some compile-time options in an H-spec so that I don't have to remember to add them every time I compile the program. For more information on prototyping specifically or on ILE in general, including an explanation of the compile-time options, check out "RPG Prototyping" or "The Basics of ILE Service Programs."

Next, I copy in the API prototype and define some parameters to pass to and receive from the API. When called, this program will accept the starting point, or seed, as a base for the random number generator. Inside the free-form specs, I first call the API. I'm not required to code the CALLP when using the free-form technique. Notice that I pass the seed as the first parameter, that the second parameter will contain my random number, and, since I am not using a condition handler in my application, that I pass the constant *OMIT as the third parameter to tell the API to ignore it.

There you have it. I added some display statements so that you could see what the API is doing. The first display operation allows you to see how the API changes the seed. The second and third display operations show you the random number using different data types. Of course, you can remove those display operations and manipulate the code however you want. The important information is contained in the prototype definition and the actual call to the API. Enjoy.