BIFs are not technically part of /Free. You can use them in RPG IV positional. But they are so much more necessary in /Free that it only makes sense for us to look at some of the most common ones and see how they are used.

Editor's Note: This article is excerpted from article 12 of 21st Century RPG: /Free, ILE, and MVC, by David Shirey.

BIFs are very, very useful. They replace the RPG tradition of moving things from one field representation to another until you get what you want. But they are not trivial. You have to look closely at what a BIF is doing, and that is particularly true if the BIF is working on another BIF. It can get complex, and you have to be very clear what you are trying to accomplish. A good source of information on BIFs and how to use them is Rafael Victória-Pereira’s excellent RPG Academy BIF series at mcpressonline.com.

Why bother with BIFs?

First, BIFs tend to be clear and self-documenting. The BIF contains keywords (e.g., NUMERIC, SUBSTRING, DATE) that help you see at a glance what is being done.

Second, if you are using various fields and MOVEs, you need to look two places to see what is going on: the code and the D-specs where these various fields are defined. There is nothing in the MOVE statement to tell you that you are going from a 10-character string to an 11-digit packed field with three decimal places. With a BIF statement, you can see all the parameters that are affecting this statement in one spot. Again, it’s clearer and more self- documenting than non-BIF code.

Third, as we shall see shortly, a BIF can operate on either a variable or another BIF (a function), meaning that you can piggyback statements and do a very complex thing in one spot.

Of course, like all heroes, BIFs have a dark side as well, something that is an inevitable outcome of the ability of one BIF to operate on another. We will touch on that as we get toward the end of this chapter, but it is not enough to make you hesitate to use BIFs.

BIF Essentials

Let’s start by taking a few minutes to look at a couple of things that make BIFs BIFs.

BIFs and Expressions

One thing you should know about BIFs is that they generally are written up to operate on a field. You know, you have a numeric field from a file, and you use a BIF to convert it to a character field. In this case, x is a string field that will carry the character representation of the numeric order number, which is the argument of the BIF.

x = %CHAR(ORDNO);

But the cool thing about BIFs is that they can also work on functions or even other BIFs. That is, instead of putting a field name in the BIF, you can use a function. Like maybe you have a function that returns today’s date, and then you convert that date to a character format. Like this:

x = %CHAR(%DATE());

That’s just a simple example. You can get real complex, believe me. And what do you want to remember when you do something like that? That’s right, get the parentheses straight. Parentheses are fundamental to organizing BIFs, and it’s important to make sure they stay balanced. And spaces are important, too. So, remember that you can embed spaces into a BIF and it is fine. It just might make it easier to read. For example, which do you prefer?

x = %XLATE(-:/:%CHAR(DATE()));

or

x = $XLATE( - : / : $char(Date()) );

Parentheses and spaces. They are the programmer’s best friend. Because six months from now, it may be pretty hard to recognize at a glance exactly what you meant to do there.

Parentheses

And speaking of parentheses, almost all BIFs use parentheses. I would look to see if there are any that don’t, but I just don’t feel like it. I don’t think there are.

The parentheses enclose the parameters that are required to make the BIF work. That is, to provide the data the BIF needs to do its thing.

You can either have the left parenthesis right after the last character in the BIF name or skip a space (or several). That is, you can either do %DATE(); or %DATE    (); and it makes no difference to the system.

But parentheses also surround BIFs within a BIF, and you will see plenty of that later.

Hate to repeat, but as I said above, you have to make sure the parentheses are balanced. Iin some very complicated BIFs, that requires some careful scrutiny.

Colon

The second thing to keep in mind about BIFs is that while many use just one parm, most of them are going to have multiple parms that need to (or can be) passed within the parentheses.

The colon is the default character to separate these parameters. We will see this portrayed in shocking detail over the next few pages. There can either be spaces before and after the colon or not, depending on what you like to see.

Oh, and for the people who are like me, if you have four parms in the BIF and only specify three of them, then you only use two colons. You don’t need to put colons in to indicate missing parms.

Semicolon

When using the BIF in /Free (it can be used in /Free or positional), you have to end the statement with a semicolon.

Now, because I have to fill up this chapter somehow, let’s look at some of the more common BIFs.

Numeric to Character

We are not going to go through every BIF—far from it. For a more in-depth and clinical look at the BIF world, I would suggest chapter 4 of Bob Cozzi’s book The Modern RPG Language or chapter 6 of Rafael Victória- Pereira’s book Evolve your RPG Coding. I just want to take a gander at a couple of the more commonly used ones and give you a flavor for how a BIF is structured and used. Let’s start our limited journey by converting some sort of numeric field or function to a character string.

%CHAR(numeric value or expression);

The first BIF we will look at is the one that converts from numeric to character representation. It’s a simple one. No colons. Or an appendix, so you never have to worry about having to remove that on a weekend.

In this format, the operator can be either a numeric value or an expression (such as another BIF).

The key to this one is that when the conversion is done, the BIF will bring over periods and commas, but will truncate any leading zeros.

So, if the numeric value is 53.46 and we are going to convert that into a six- position alphanumeric field, then it will appear in that field as 53.46, rather than 053.46.

%CHAR(date-time value : format);

There is one more format of the %CHAR BIF that we should look at because it differs in one important aspect. And this is if we use a date-time value or expression in the %CHAR BIF.

In this case, there is one additional parm: the format of the character string we want returned. That is, ISO, MDY, whatever valid date-time format we want to use.

If you do not specify a format, then it defaults to ISO. Just keep that in mind.

Convert to Decimal

Oh, yeah, baby. What goes around comes around. We don’t just convert from numeric to character. That coin has two sides, Mama. And now it’s time to flip that sucker over and see what comes up.

%DEC() and %DECH()

I am going to deal with these two simultaneously because they are roughly the same thing, except that %DECH throws in the half adjust to round the result.

These may be used in a couple of situations, although the general thrust is to convert to a numeric (that is, packed) format.

The first is to convert either a numeric expression or a character string to a packed field. This can be done by either %DEC and %DECH. The format is:

%DEC(input string : [length : decimal-positions];

Length and decimal positions cannot be an expression (like a BIF) but must be a literal or named constant. The reason for using these two parms is simply to format and restrict the length of the output field. If you don’t care, then you don’t need them. Screw ’em. Unless you are using the %DECH BIF. Then you need the length and decimal positions in order to know how to do the rounding. If you are converting from a character string, then the length and decimal positions are required.

When I say “numeric value” going into the conversion, there are some limitations.

First, it can’t be floating point. You need to use %FLOAT for that.

Second, it can’t contain thousands separators (,).

Third, it can have a plus (+) or minus (–) sign either before or after the value, a decimal point, and blanks at any point in the field.

You can also use the %DEC to convert dates or times to a numeric (packed) representation. That is, it converts a value from a date-type field to a non-date numeric field.

The result can be either a six-digit or an eight-digit field. How do you determine which? If you set a six-digit field to be the recipient of the BIF, you get six digits. If you use an eight-digit field, you get eight. Seems pretty clear to me.

An optional parameter that can be used is the date format that you want the non-date numeric field to come out in. If you don’t specify anything, then it uses *ISO (YY-MM-DD or YYMMDD).

The same is true for times, except that the output is always six positions and the default is *USA.

See how simple BIFs are? No smart talk now. It wasn’t that simple when you used the MOVE and a hundred intermediate fields.

Next time: The Importance of BIFs, Other Conversions BIFS  You can pick up Dave Shirey's book, 21st Century RPG: /Free, ILE, and MVC, at the MC Press Bookstore Today!

David Shirey is president of Shirey Consulting Services, providing technical and business consulting services for the IBM i world. Among the services provided are IBM i technical support, including application design and programming services, ERP installation and support, and EDI setup and maintenance. With experience in a wide range of industries (food and beverage to electronics to hard manufacturing to drugs--the legal kind--to medical devices to fulfillment houses) and a wide range of business sizes served (from very large, like Fresh Express, to much smaller, like Labconco), SCS has the knowledge and experience to assist with your technical or business issues. You may contact Dave by email at This email address is being protected from spambots. You need JavaScript enabled to view it. or by phone at (616) 304-2466.

---

MC Press books written by David Shirey available now on the MC Press Bookstore.

		21st Century RPG: /Free, ILE, and MVC Boost your productivity, modernize your applications, and upgrade your skills with these powerful coding methods. List Price $69.95 Now On Sale

Also Read

Advanced/Free - Function Calls and Return Values

PRACTICAL ILE - ILE Service Programs

Data-Manipulation Operations Using Free Format, Part Two