RPGLE File and Error BIFs Reference

This page is a lookup for the RPGLE built-in functions that report what happened after a file operation: %found, %eof, %equal, %error and %status. It maps each function to the operations that set it, and lists the cases where a test reads a stale or unexpected value.

For how file input and output works, read the lessons in the RPGLE series. For the older indicator forms, see RPGLE Calculation Specs and Logic Blocks. The complete list of BIFs is in the RPGLE Built-in Functions Reference.

All examples are free-form RPGLE.

File and error BIFs at a glance

Each of %found, %eof and %equal takes an optional file name. Without it, the function returns the value set by the most recent relevant operation. With it, the function returns the value for the most recent relevant operation on that file.

Which operation sets which BIF

%FOUND

%found{(file_name)}

Returns *on if the most recent relevant file operation found a record, a string operation found a match, or a search operation found an element.

chain keyVal orderFile;
if %found(orderFile);
  // the record exists
else;
  // no record with that key
endif;

%EOF

%eof{(file_name)}

Returns *on if the most recent read operation ended in an end-of-file or beginning-of-file condition. Test it after every read.

read orderFile;
dow not %eof(orderFile);
  // process the record
  read orderFile;
enddo;

A successful chain, setll or setgt sets %eof(file) off. An unsuccessful one leaves it unchanged.

%EQUAL

%equal{(file_name)}

Returns *on if the most recent setll found a record whose key equals the search argument, or a lookup found an element that exactly matches. setll positions the file whether or not the key is present, so %found and %equal are how you tell what it found.

setll keyVal orderFile;
if %equal(orderFile);
  // at least one record has exactly this key
endif;

%ERROR

%error

Returns *on if the most recent operation with the (e) extender ended in an error. The system resets %error to off before each operation that has the (e) extender, and it stays unchanged afterwards if no error occurs. callp can set it as well.

chain(e) keyVal orderFile;
if %error();
  // the read failed for a reason other than "not found"
endif;

A record that is not found is not an error. Use %found for that.

%STATUS

%status{(file_name)}

Returns the most recent program or file status code. It starts at 00000 and is reset to 00000 before any operation with the (e) extender begins. Read it straight after an operation with (e), or at the start of an error subroutine, so a later operation does not overwrite it.

chain(e) keyVal orderFile;
if %error();
  status = %status(orderFile);     // for example 01216 when the record is already locked
endif;

Choosing between %FOUND, %EOF and %EQUAL

• After chain, test %found. The record either exists or it does not, and after a chain that finds nothing the file must be repositioned before the next read. The opcode is covered in the RPGLE CHAIN Opcode Reference.
• After a read family operation, test %eof. A read does not set %found.
• After setll, test %equal to ask whether the key is present, and use %found when you only need to know whether a record at or after the key exists. See the RPGLE SETLL and SETGT Opcode Reference.
• After a search of an array or a table with the lookup opcode, %found and %equal have the same meanings as for files.

Test the function immediately after the operation. Any other operation on the same file in between can change the value, and an operation on another file changes the value that you get without a file name.

A complete read pattern

The common pattern reads every record for one key. It uses setll to position, reade to read while the key matches, and %eof to stop. The RPGLE READ, READE and READP Opcode Reference covers the loops in detail.

setll keyVal orderFile;
reade keyVal orderFile;
dow not %eof(orderFile);
  // process the record
  reade keyVal orderFile;
enddo;

For reade, %eof becomes on when the next record has a different key as well as at the end of the file, so the loop ends cleanly in both cases.

Legacy indicators

Fixed-format code used result indicators for the same jobs. They still compile; use the BIF in new code.

Common mistakes

• Testing %eof before the first read, or only once after the loop.
• Reading %found after %scan and expecting it to reflect the %scan.
• Treating “record not found” as an error. It is not; test %found.
• Testing %error when the operation has no (e) extender. Without it, %error is not set and an error raises a run-time error instead.
• Reading %status after later operations have changed it.

FAQ

What is the difference between %FOUND and %EQUAL?

%found says whether a record or element was found. %equal says whether the match was exact. After setll, %found and %equal can differ: setll positions the file even when no record has the key.

Do I need %ERROR if I test %FOUND?

Yes, for different problems. %found reports a missing record. %error reports a failure such as a locked record or a file that is not open, and only when the operation has the (e) extender.

Does CHAIN change %EOF?

%eof reports the last read. A successful chain sets it off, and an unsuccessful chain leaves it as it was.

Summary

• Pair this page with RPGLE Calculation Specs and Logic Blocks and Error handling in RPG.
• Return to the RPGLE Built-in Functions Reference to find the other BIF families.