Who Owns the Record Layout? Externally Described vs Program-Described Files

Every file declaration in an RPG program answers one question: where is the record layout defined? The answer determines what happens when that layout changes.

Externally described

The layout lives in the file object — defined once with SQL CREATE TABLE or DDS. The compiler retrieves it and generates the record format and every field. Every program that uses the file inherits the same definition, and the declaration is a single line.

Program-described

The file supplies only a record length. In free format, DISK(80) makes a file program-described, and a data structure with POS-positioned subfields defines the meaning of every byte. This is the right tool for flat interchange files from banks, suppliers, and legacy systems.

dcl-f PRICEIN disk(80) usage(*input);

dcl-ds priceRec len(80) qualified;
  itemNo   char(15)   pos(1);
  newPrice zoned(9:2) pos(16);
  effDate  char(8)    pos(25);
end-ds;

The level check

A program compiled against an externally described file stores the file's record format level identifier. If the layout changes, the next open fails with CPF4131. That failure is the system preventing a program from processing records under a layout it was not built for. The correct response is to recompile, not to suppress the check.

No safety net for flat files

Program-described files have no level check and no data validation. If a partner widens one field, every later field shifts. The program either fails on invalid data or, more dangerously, writes plausible but wrong values. Production code validates every record — for example, %CHECK on a character overlay of a numeric field and TEST(DE) on dates.

Adapting an external description

RENAME fixes a record format that shares the file's name. PREFIX separates identically named fields from two files. EXTNAME and LIKEREC build data structures from a file's layout without retyping it.

Lesson 23's exercise inspects a real IBM-supplied file with DSPFFD and DSPFD, then builds both kinds of file on PUB400 and runs the daily price update against them.

Get the lesson

Lesson 23, “Externally Described vs Program-Described Files,” is part of Beginner ILE RPG in IBM i ILE RPG Mastery and is available at ILERPG.com for USD 10. The complete Beginner ILE RPG series — all 18 lessons — is USD 180, or USD 135 with coupon code RPG30, which takes 25% off when you purchase the full series.