Throughout this series, I've mentioned BIFs several times. It's time to explain a few of them in detail, starting with a couple of almost-magical BIFs that rid your code of those pesky file-related indicators. Interested? Keep reading.

We all use a built-in function (BIF) or two in our code, even if we don't quite understand how they work. Here and in upcoming TechTips, I'll discuss an assortment of BIFs that will, hopefully, help you to BIF up—sorry, I mean beef up—your code: you'll improve readability, avoid "reinventing the wheel" by writing code that emulates the functionality of a BIF, and make yourself (and your code) more efficient.

What Does That *IN70 Mean?

We've had those moments, either when writing or debugging code, when we look at a statement that uses an elusive file-related indicator and we have no idea what it's being used for. Been there? I have! But after reading this TechTip, you'll have the necessary tools to never go there again!

RPG provides us with two native ways to read a file: you either read it sequentially (starting on the first or a specific record that matches some sort of key), using SETxx and READxx, or go directly to a certain record, using CHAIN. You're probably used to seeing indicators associated with these operations, as in the following example:

C     *LOVAL       SETLL     MYFILE                    

C                   READ     MYFILE                                 70

C                  DOW       NOT *IN70                              

* The cursor is positioned and the first record was read

* do something with it...

C                   READ     MYFILE              

C                   ENDDO

Let's take this example and start with the sequential read. There are two SETxx operations: SETLL and SETGT. The SETLL operation positions a file at the next record that has a key or relative record number that is less than or equal to the search argument (key or relative record number) operand specified; that's the *LOVAL in the example above. SETGT is basically the same, but it positions a file at the next record that has a key or relative record number that is greater than or equal to the record in the search argument. These operation codes usually precede a READxx operation that uses an indicator. After the READxx operation, some sort of check over the indicator is performed with an IF or DOW/DOU operation code.

This should be familiar, but it never hurts to do a little recap. Now let's get rid of that indicator, shall we?

Let's Start at the End—End of File, Actually

The first BIF I'm going to discuss is %EoF (or end of file). The %EoF BIF returns '1' (or *On) if the most recent read operation from a file ended in an end-of-file or beginning-of-file condition; otherwise, it returns '0' (or *Off). Since it returns the condition of the latest read file and this might be confusing in the middle of a piece of code that includes several READxx operations to different files, you can (optionally, but I strongly recommend that you always do) pass the file name as a parameter. So, our little example, minus the *IN70 indicator and using the

%EoF BIF, looks like this:

C     *LOVAL       SETLL     MYFILE                

C                   READ     MYFILE                

C                   DOW       NOT %EOF(MYFILE)      

* The cursor is positioned and the first record was read

* do something with it...

C                   READ     MYFILE              

C                   ENDDO

What's the result? Improved readability and no file-related indicator! You can use %EoF with all the READxx operations. If (and only if) you're writing to a subfile, you can also use %EoF to check whether the WRITE operation was successful.

Still CHAINed to Indicators?

IBM calls CHAIN "Random Retrieval from a file" with good reason: if you happen to have more than one record that matches the search argument supplied, the first found is returned. I'm not exactly sure how the first is chosen, but I suspect that "Random" in the name has something to do with it… Anyway, here's an example of a common use of a CHAIN:

C     KEYFIELD    CHAIN     MYFILE                             77

C                   IF       NOT *IN77                          

* The record was found, do something with it...

C                   ENDIF

See that pesky *IN77 there? Let's get rid of it! While %EoF is READxx's natural partner, CHAIN prefers to pair with %FOUND. The %FOUND BIF returns '1' if the most recent relevant file operation found a record (among other uses that I'll discuss later). Otherwise, this function returns '0'. Just like %EoF, it accepts the file name as parameter, and it's the perfect replacement for the indicators usually associated with the CHAIN operations. Taking the example above and this little piece of knowledge, let's BIF up the code:

C     KEYFIELD     CHAIN     MYFILE                      

C                   IF       %FOUND(MYFILE)            

* The record was found, do something with it...

C                   ENDIF

Note that the *IN77 indicator, as well as the NOT operator, disappeared, thus making the code more readable! You can also use the %FOUND BIF with the DELETE operation code and some string-related operation codes (I'll cover those in a future TechTip about strings and their BIFs).

There's also a %EQUAL BIF, normally used to replace the SETLL-related indicators. I never used an indicator in SETLL (usually the indicator is in the READxx operation that invariably follows), so I don't see the point of it, but I thought I should mention it anyway.

I hope that this is useful and that it helps you improve your code. The next TechTip will be about data-type conversion BIFs, which you might use to ban some, if not all, MOVE and MOVEL operations from your code! Until then, feel free to comment, agree, disagree, or simply speak your mind in the comments section below or in the usual LinkedIn groups that my TechTips usually end up in.

Rafael Victória-Pereira has more than 20 years of IBM i experience as a programmer, analyst, and manager. Over that period, he has been an active voice in the IBM i community, encouraging and helping programmers transition to ILE and free-format RPG. Rafael has written more than 100 technical articles about topics ranging from interfaces (the topic for his first book, Flexible Input, Dazzling Output with IBM i) to modern RPG and SQL in his popular RPG Academy and SQL 101 series on mcpressonline.com and in his books Evolve Your RPG Coding and SQL for IBM i: A Database Modernization Guide. Rafael writes in an easy-to-read, practical style that is highly popular with his audience of IBM technology professionals.

Rafael is the Deputy IT Director - Infrastructures and Services at the Luis Simões Group in Portugal. His areas of expertise include programming in the IBM i native languages (RPG, CL, and DB2 SQL) and in "modern" programming languages, such as Java, C#, and Python, as well as project management and consultancy.

---

MC Press books written by Rafael Victória-Pereira available now on the MC Press Bookstore.

		Evolve Your RPG Coding: Move from OPM to ILE...and Beyond Transition to modern RPG programming with this step-by-step guide through ILE and free-format RPG, SQL, and modernization techniques. List Price $79.95 Now On Sale
		Flexible Input, Dazzling Output with IBM i Uncover easier, more flexible ways to get data into your system, plus some methods for exporting and presenting the vital business data it contains. List Price $79.95 Now On Sale
		SQL for IBM i: A Database Modernization Guide Learn how to use SQL’s capabilities to modernize and enhance your IBM i database. List Price $79.95 Now On Sale

Also Read

Programming in ILE RPG - Defining Data Structures, Part I

H and F Position-less Specs

Practical RPG: AI and IBM i