Using the C run-time library functions and setting up the prototypes for C functions is an easy way to use features available in the C language.

Note: This article is an excerpt from the book Functions in Free-Format RPG IV, published by MC Press.

Most RPG programmers don't know the C programming language and avoid technical articles or discussions that have anything to do with it. Until 1993, so did I. That year, I took some college classes in which C was the only language that could be used for assignments. I found that C was very different from RPG, but writing my own functions was very appealing. When I returned to an RPG environment in 1994, I assumed that I would not see any C programming again. In late 1994, however, IBM introduced RPG IV and ILE. At that point, integrating C functions with RPG IV programs became a possibility. 

Why Use C Functions?

The RPG IV language has a rich complement of op-codes and BIFs, so why would you consider accessing functions designed for the C language? The answer is that the C language gives you some functions you don't have in RPG, as well as functions that are more efficient than native RPG operations. Integrating C functions with your normal RPG code is easy, giving you the best of both languages.

To access a C function, you need to know the function's interface, including its name, number of parameters, parameter data types, and return value, if any.

To see why C functions might be useful to RPG programming, let's look at a few examples. Let's start with the C function Rand, which is used for random number generation. It has to be initialized with another function, called Srand, which "seeds" the random number generator. The notion of seeding is to set an initial value that is kept in the system somewhere. The Rand function cannot be used without first doing Srand, which must be run only once.

Here are few technical details to keep in mind when using these functions:

• Srand requires an unsigned integer parameter, and there is no return value.
• Rand has no parameters and returns an unsigned integer return value.

 You'll see examples that use both the Rand and Srand C functions later in this chapter.

Now, let's look at another C function, Strtok. This function is called string-token, and it is a string parser. For example, consider the string "The cat is gray." This string can be broken into separate tokens of "The," "cat," "is," and "gray" by using this function repetitively.

Here are few technical details to keep in mind when using this function:

• Strtok requires a string parameter and a delimiter character.
• The return value for Strtok is either a pointer to a token (a character string up to the first delimiter) or a null pointer.
• It is common practice to use a blank as the delimiter, but other characters can be used.

You'll find an example that uses the Strtok function later in the chapter.

Now, let's consider a higher math function, Sin (the trigonometric function sine). Here are few technical details to keep in mind when using this function:

• The Sin function has one parameter, the angle in radians.
• It must be defined as a floating-point data type, either 4f or 8f.
• The return value is also floating-point.

Review the IBM reference manual ILE C/C ++ Runtime Library Functions Reference for details on these or any other C functions you might be interested in. The document number is SC41-5607. This IBM publication can be viewed on the Web at the following link:

http://publib.boulder.ibm.com/infocenter/systems/scope/i5os/topic/books/sc415607.pdf

How C Functions Work with RPG IV

Using a C function within an RPG IV program requires the use of a prototype. The prototype defines to RPG IV the function's return value (if any) and the parameters needed for the function.

For example, consider this use of the Sin function:

dsin             pr             8f   extproc('sin')

d angle                         8f   value

The prototype name is made the same as the C function. The return value definition of 8f is specified, and the external procedure name is specified ('sin'). On the second line, the name angle is optional, since names on prototype parameters are not required. The 8f is the definition of the parameter, and the keyword value is used, since parameters in C functions expect parameter passing by value.

The call interface is the same as for any external procedure. The CallP operation can be used if no return value is needed. The implicit call (which works just like a BIF) is used when the C function has a return value. As you will see throughout this book, the implicit call is emphasized as a preferred method.

Let's add a few more lines of code to the example above:

dSinans          s             8f

dAngleF           s             8f

dAngleP           s              7p 2   Inz(1.0456)

/free

   AngleF = %float(AngleP);

   SinAns = sin(AngleF);

Three fields are defined:

• Sinans will hold the answer.
• AngleF is a floating-point work field.
• AngleP is the input angle, in packed-decimal format.

The first new line of code uses the %float BIF to convert the packed-decimal AngleP field to floating-point and then assigns the value to the work field AngleF. The next line of code calls the function Sin implicitly, passing the work field AngleF as a parameter.

Random Numbers from C

One of the C functions that you might find useful is the random number function, mentioned earlier in this chapter. You'll see a detailed example using this function later, but for now, let me share the justification for using it in an application. The following situation occurred a couple of years ago:

I was working on an application to perform testing—giving an exam. The exam had four parts, with 10 questions in each part. The questions for each part came from a question pool, with 100 possible questions in the pool. The program needed to select, at random, 10 questions from each of the four associated question pools.

RPG IV does not have a random number function, but C does. Upon investigation, the Rand function in the C language was determined to be the proper choice. As explained earlier, Rand needs to be initialized by another C function, Srand.

The output from Rand is an integer between zero and 32,767. For the purposes of this application, I needed to scale that down to a range of zero to 99. A handy way to do this is to divide the return value by 100 (in this case) and use the remainder.

Because duplicate questions were not wanted in the exam, a check for a duplicate random number was needed, and duplicates discarded. The exam questions were stored in an array with indexes from one to 100, so the resulting random number needed to be incremented by one to match the RPG array index. Prototyping was needed for the two C functions, Rand and Srand, as follows:

D Set_random         PR                 Extproc('srand')

D     Seed                   10u 0

D Get_random          PR        10u 0     Extproc('rand')

Notice the use of the Extproc keyword and the C function name in lowercase. This is required. For the Set_random prototype, there is no return value (the "seed" is stored somewhere in the system), but there is an unsigned integer requirement as the parameter. It is best to make this parameter as random as possible. I have found that using the micro-seconds value of the current timestamp is fairly random.

Also, ILE needs to locate the procedures rand and srand, so a binding directory needs to be specified on the H control specification. The H control specification must be placed first in the source member. Here is an example:

H     Bnddir('QC2LE')

Random number setup can be done as follows:

D Seed               S          10u 0

D Index             S          10i 0

/free

Dou Seed <> 0;

     Seed = %subdt(%timestamp( ) : *MS);

     If Seed <> 0;

       Set_Random(Seed);

     Endif;

Enddo;

   // Obtaining the random number,

   // then scaling it to 0-99 is done as follows:

index = Get_Random( );     // index 0-32767

index = %rem(index:100);   // index 0-99

index += 1;                // index 1-100

The code above sets the seed (in the Dou group) and then uses the random number function to set an index. The index is used to access an array element from a question pool. Additional programming is needed to avoid duplicate indexes. The index is used to access a question from a question array.

Checking for duplicate random numbers and further processing of the application is not shown here.

Occasionally, the need for higher mathematical functions comes up. This might involve the use of trigonometric functions such as sine, cosine, or tangent. These are not available in RPG IV, but all of them are available in C.

The following trig functions are available in C:

• Acos calculates the arc cosine.
• Asin calculates the arc sine.
• Atan calculates the arc tangent.
• Atan2 is a variation of Atan for calculating the arc tangent.
• Cos calculates the cosine.
• Cosh calculates the hyperbolic cosine.
• Sin calculates the sine.
• Sinh calculates the hyperbolic sine.
• Tan calculates the tangent.
• Tanh calculates the hyperbolic tangent.

Using the C run-time library functions and setting up the prototypes for C functions is an easy way to use features available in the C language.