02
Sat, Nov
2 New Articles

TechTip: Using C Functions, Part II

General
Typography
  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

C functions provide capabilities that are useful to you as an RPG IV programmer.

 

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

 

The data types used by C functions are nearly all integer, float, and null-terminated strings. RPG IV supports all integer and float data types, and can convert null-terminal strings to RPG character fields, and vice versa (using the %str BIF). The integer and float data types available with RPG IV make it easy to pass variable data back and forth between RPG IV and C.

 

One of the hurdles for RPG IV programmers is understanding the data types used by C and matching them to RPG IV's scheme. Typically, RPG programmers have only used zoned or packed decimal numeric fields. Table 3.1 describes how data types in the two languages relate to each other, including recommended RPG variable sizes.

 

Table 3.1: Most Common Data Types for C and RPG IV

C Definition

RPG IV Prototype Parameter Definition

Notes

int short

5i 0

Signed integer, two bytes

int long

10i 0

Signed integer, four bytes

unsigned int

5u 0

Unsigned integer, two bytes

unsigned int long

10u 0

Unsigned integer, four bytes

Float

4f

Floating-point, standard precision

Double

8f

Floating-point, double precision

Char *

*

Defined in RPG with the VALUE and Options(*String) keywords

(*)

*

Defined in RPG with the VALUE and PROCPTR keywords

 

Parameter Passing to C Functions

When passing parameters to another procedure, RPG normally uses a technique called passing by reference, which means that a pointer address is used. In the called program, the parameter field is a template over the "passed" field in the calling program. If you modify the variable in the called program, you are really modifying the field in the calling procedure.

 

The C language uses a parameter-passing technique called passing by value. In this scheme, the actual value of the parameter is passed. The value of the passed field can be changed in the called procedure, but the parameter field in the calling program is not changed. The RPG IV language can also pass parameters by value, simply by using the VALUE keyword for the parameter in the definition on the prototype.

 

A more flexible option is to use the keyword CONST instead of VALUE. This also passes parameters by value but has some additional features. The CONST keyword allows you to use fields of different data types (for numeric data types) and lengths as a parameter (different than the prototype), including the use of a constant.

Character String Differences Between C and RPG IV

The RPG IV language and C differ in their method of handling character strings. RPG IV uses fixed- or varying-length character fields. The C language uses an array of a variable length, with the last entry in the array a null character (hex '00'). If you use the Options(*String) keyword on the parameter in the prototype for a character field, the compiler places the RPG IV character field specified into a work area and then automatically adds the null character. The data in the work area is then passed to the C function.

Binding RPG IV and C Functions

After coding an RPG IV program with the proper prototypes and using an implicit call to the C function using the prototype(s), there is still one more step to "glue" the pieces together. The C functions are in service programs known only to IBM, but IBM has given us access to these programs via binding directory QC2LE. By simply putting Bnddir('QC2LE') on the H control specification, the binder will locate and include the C functions you have requested.

 

You must also specify an activation group, but not the default activation group, since you are using ILE's binding by reference. While you are testing your new program, use *New as the activation group. This helps avoid testing problems. Otherwise, named activations stay around and are used on subsequent calls, even if you recompile and replace the program.

 

Here's an example of an H control specification:

 

H Bnddir('QC2LE') Actgrp(*New)

 

This specifies that binding directory QC2LE be used during the binding phase and that activation group *New be applied when the program is loaded and run. When you are past the testing phase, a named activation group might be your best alternative.

Using C Functions to Make Your Job Easier

I was asked to help with a data conversion where the customer name in the "from" database was one big field, with spaces separating the parts of the name. In the "to" database, the name was divided into title, first name, middle initial, and last name fields. Other information about the "from" database included the following:

 

  • Not every name had a title, but if a title existed, it was a standard title.
  • A middle initial was optional, but if it existed, there was a period after it.
  • Every character after the middle initial was part of the last name.
  • If only one name appeared, it was the last name, not the first name.

 

Moving each part of the multi-part name field into the right new field became a programming project. It was accomplished completely in RPG IV, but a nagging inner voice kept saying to me, "This task could have been done more easily, somehow." After some research, I found a C function that could have helped: the Strtok (string token) function.

 

This is a parser-type function that helps in dividing portions of a character string. Something in the string has to be the delimiter, to tell the parser where one portion ends and the next begins. The C language calls these short string portions tokens. For example, using the Strtok function with the sentence "See Spot Run" and a space as the delimiter, you get "See" with one pass, "Spot" with a second pass, and "Run" with a third pass. This scheme would fit my data conversion situation pretty well, where blanks would be used to separate parts of the big name field. Of course, some logic would still need to be used to place each "token" item into its rightful place.

The Strtok Function

We'll review the most important elements of the new Strtok program in this section. (The entire program takes over a hundred lines of code, so it is not included here.) The field with the name to be parsed is FullName, defined 40A.

 

The first part of the main procedure is shown here:

 

h Bnddir('QC2LE') Actgrp(*New)

d GetToken           pr       *     ExtProc('strtok')

d Name                       *     Value Options(*String)

d Delimit                    *     Value Options(*String)

 

It has the H control specification with the IBM binding directory QC2LE specified, and the activation group *New. Following that is the prototype for the Strtok C function. The return value is a pointer to the found token or a null pointer if no token is found. The two parameters are the field to be parsed and the delimiter.

 

The next section is a work array to hold all of the tokens, and a work field to hold the most current token:

 

d artok           s                 like(FullName) dim(30)

d token           s                 like(FullName)

 

The next few lines are work fields used in the procedure. The definition 5u 0 indicates an unsigned integer of five digits:

 

d ReturnAdr       s           *

d count           s        5u 0

d Space           c                 ' '

 

The count field defined here is used to count the number of tokens found, and used later in processing the token array elements.

 

The procedure begins by clearing the previous contents of the Title, FirstName, Initial, and LastName fields:

 

/free

//* Clear output fields

   Clear Title;

   Clear FirstName;

   Clear Initial;

   Clear LastName;

 

The procedure continues by first checking for all-blank input. Next, it left-adjusts the FullName field and then retrieves the first token from the FullName field:

 

   If FullName <> *blank;

     // Name is not all blank

     // Shift Name to left, removing left blanks

     FullName = %triml(Fullname);

     ReturnAdr = GetToken(FullName:Space);

 

The function call GetToken here gets the first token. In the next section, GetToken gets the remaining tokens.

 

The next section is a loop to obtain and store the tokens of the FullName field:

 

   Dow ReturnAdr <> *Null; // Load Tokens into Artok array

     Token = %str(ReturnAdr);

     Count += 1;

     Artok(count) = %trim(Token);

     ReturnAdr = GetToken(*Null:Space);

   Enddo;

 

Notice that the return value for the C function is a pointer to the token. The %str BIF takes the null-terminated string and moves the characters into a regular character-field token. A count is made of how many tokens are saved in the array, to handle later processing. At this point, the tokens are stored in elements of the Artok array.

 

The use of the Strtok C function makes parsing the long FullName string very easy. The remainder of the program, not shown here, just puts the tokens in the correct output fields.

Exponentiation

There was a time when RPG could do little in the way of powers and roots. Powers were done by repetitive multiplications, and the only "root" capability was the square root. The use of C functions was the only solution for anything more complex. You might have done this.

 

It might seem contrary to bring this up in a chapter on using C functions, but the truth of the matter is that native RPG can now provide all you need in this mathematical arena.

 

With the advent of the ** (exponentiation) operator, all business formulas using an exponent can be done without using the C function library. In RPG IV, the exponentiation operator gives you the complete capability to determine the root or power of a number.

 

The form of an exponentiation operation is as follows:

 

     Answer = number ** power;

 

In this formula, "power" can be a whole number, a fraction, or a mixed number. It can also have a negative sign.

 

Here are several examples of exponentiation, for your review:

 

   /free

     // Simple power and roots:

     Area_Circle = 3.1416 * Radius ** 2;

     //   The above computes the area of a circle using the power 2

     Cube_Root = 8 ** (1/3);

     //   The above line computes the cube root of 8, making Cube_root = 2

     Future_Val_Annuity = Period_Amt * (((1+i)**n-1)/i);

    //   The above expression computes the future value

     //   of an annuity. i is the periodic rate, and n

     //   is the number of periods. With this formula, you can

     //   determine how much money you will have if you save

     //   Period_Amt for n periods at interest rate i.

 

As you can see, any formula needing exponents can be done without using C functions.

Summary

C functions provide capabilities that are useful to you as an RPG IV programmer. In particular, if you have a math requirement needing the use of trigonometry or other higher mathematics, the appropriate C function will make the overall programming much easier. Other specialized C functions, such as the random number generator, are helpful for special projects.

 

The example of the Strtok C function in this chapter shows that combining C functions with native RPG operations enhances your overall programming toolset.

 

JIM MARTIN

Jim Martin holds a BS degree in mathematics and an MS in computer science. For 26 years, he was employed by IBM, where he wrote RPG applications for customers and worked in the programming laboratory as a programmer on portions of CPF and the OS/400 operating system. After leaving IBM, Jim took post-graduate work in computer science and performed RPG training. He is an IBM-certified RPG IV developer and author of multiple bestselling editions of Free-Format RPG IV, which, since the book's initial publication in 2005, have taught thousands of RPG IV programmers how to be successful with the free-format coding style.


MC Press books written by Jim Martin available now on the MC Press Bookstore.

Free-Format RPG IV: Third Edition Free-Format RPG IV: Third Edition
Improve productivity, readability, and program maintenance with the free-format style of programming in RPG IV.
List Price $59.95

Now On Sale

Free-Format RPG IV: Second Edition Free-Format RPG IV: Second Edition
>Make the transition from coding in fixed-format RPG to free format.
List Price $59.95

Now On Sale

Functions in Free-Format RPG IV Functions in Free-Format RPG IV
Here’s the ultimate guide to writing RPG IV programs with functions in the free-format style.
List Price $59.95

Now On Sale

BLOG COMMENTS POWERED BY DISQUS

LATEST COMMENTS

Support MC Press Online

$

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now!  Request Now.

  • SB HelpSystems ROBOT GenericForms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn: