ILE RPG requires that you declare (define) all the files, variables, and other data items used in your program.

By Brian Meyers and Jim Buck

Editor's Note: This article is excerpted from chapter 4 of Programming in ILE RPG, Fifth Edition.

You must name all the files and instruct the compiler how the program is to use them. In addition, you must name all the other data items and specify their attributes. The declarations section must appear in your source code, following control options (if present), before any processing takes place. Declarations define these items to your program:

• Files
• Named constants
• Standalone variables
• Data structures
• Prototypes
• Procedure interfaces

Depending upon the type of data item you are declaring, RPG uses the following instructions:

• Dcl-f (Declare file)
• Dcl-c (Declare constant)
• Dcl-s (Declare standalone variable)
• Dcl-ds (Declare data structure)
• Dcl-pr (Declare prototype)
• Dcl-pi (Declare procedure interface)

This chapter explains how to define files, named constants, standalone variables, and data structures. Chapter 13 covers prototypes and procedure interfaces.

Declarations can appear in any order, although it is useful for maintenance purposes to group the declaration types together and to arrange them in alphabetic order. Because declarations concentrate data definitions into a single group of consecutive statements near the beginning of your program, they facilitate later program maintenance.

Declaring Files

Chapter 2 introduced the Dcl-f (Declare file) instruction, which describes each file the program uses and defines how to use that file. The general format of the Dcl-f instruction is as follows:

When a program declares a file, all the record formats and fields in that file become available to the program. No further declarations are necessary for the program to use those items. In the following code, file Customers contains the data you want to process. The output of your program is a printer file.

Filename

The first entry following the Dcl-f instruction names the file. The filename is the only required entry for the Dcl-f instruction. An externally described file must exist at the time you compile the program. A program-described file need not exist at compile time because the compiler contains all the information it needs to compile the program. But when you eventually run the program, the file must be available.

Device

The entry following the filename indicates the device associated with a file. The three most frequently used device keywords are as follows:

• Disk—for database files
• Printer—for reports
• Workstn—for interactive displays (discussed in Chapter 12)

RPG assumes the file is an externally described file. You can, however, specify *EXT for an externally described file:

But if the file is a program-described file, you must indicate the record length with the device keyword:

The record length for a program-described file can be from 1 to 32,766 bytes.

The filename and device entries are positional; that is, they must be entered in the correct order on the Dcl-f line: filename, then device. You can enter the remaining file keywords in any order. If no device entry exists, the compiler assumes that the device is Disk and that the file is externally described. The following file declarations are equivalent:

File Usage

The Usage keyword specifies how the program is to use the file. For example, an input file contains data to be read by the program, whereas an output file is the destination for writing results from the program. A program can use a file many ways, so several values are necessary for the same Usage keyword. The following Usage entries are valid:

• Usage(*Input)—the program can read existing records from a file
• Usage(*Output)—the program can write new records to a file
• Usage(*Input:*Output)—the program can read records and add new ones.

• Usage(*Update)—the program can change (but not delete) existing records in a file
• Usage(*Delete)—the program can delete existing records from a file
• Usage(*Update:*Delete)—the program can change or delete existing records.
• Usage(*Update:*Delete:*Output)—the program can change, delete, or add new records.

Which entry you use will depend upon the program’s purpose. Chapter 9 details how to access and update database files.

If you don’t specify a Usage keyword, the usage depends upon the device. When the device is Disk, RPG assumes Usage(*Input), and when the device is Printer, RPG assumes Usage(*Output). For device Workstn, RPG defaults to Usage(*Input:*Output). The following lines are equivalent:

or (omitting Usage):

or even (omitting Disk device):

Tip

As a general rule, the Usage keyword is required only for Disk files that have capabilities beyond simple input. The other Usage defaults, for Printer and Workstn files, are appropriate assumptions.

File Keywords

In addition to Device and Usage, the Dcl-f instruction supports a number of other keywords to expand on the basic file declaration. Following are some frequently used file keywords:

• Oflind
• Keyed, Keyloc
• Rename, Prefix
• Extdesc, Extfile, Extmbr

Previous chapters have already covered the Oflind (Overflow indicator) keyword, which associates an indicator with a printer file’s page overflow condition.

Keyed, Keyloc

The Keyed keyword specifies to process the file by key instead of using arrival sequence. To manage an externally described file by key, simply include the Keyed keyword with no additional values:

For a program-described file processed by key, you must include some additional information, as the following example shows:

This specification names the Customers file as a program-described file processed by key. The Keyed(*Char:5) entry indicates that the key is alphanumeric (the only type of key Dcl-f allows for a program-described file) and five bytes long. The Keyloc(2) entry informs the compiler that the key begins in position 2 of the record layout. If the Keyloc keyword is missing for a program-described file, RPG assumes the key begins at the first position in the format.

Rename, Prefix

Recall from Chapter 3 that SQL supports the RCDFMT clause to name a record format for a file. If, however, you create a file without using that clause, the SQL Create Table statement creates a record layout with the same name as the table name. RPG requires that the record format name be distinct from the filename. In this case, the Dcl-f instruction can rename the record format within the program:

In this example, the Customers file also has a record format named Customers. However, the RPG program will rename the format Custrec.

The Rename keyword might also be useful when two files used by a program have the same record format. For example, if the two files Customers and Custnames both have record layouts called Custrec, you can rename one or both of the record formats to differentiate them:

A related keyword, Prefix, facilitates renaming individual fields in an externally described file. For example, in the preceding Rename example, if both Customers and Custnames have identically named fields, you can prefix one or both of the files by adding the Prefix keyword:

The RPG program then knows all the fields in the Custnames file as C2Custno, C2Clname, C2Cfname, and so on. Fields in the Customers file retain their original names.

If the files already use a prefix as part of a database naming convention, Prefix can replace the existing prefix (or a part of it):

Let’s assume here that both Customers and Custnames have fields named CuCustn, CuName, CuAddr, and so forth. In this program, the fields in Custnames are referred to as C2Custn, C2Name, C2Addr, replacing the first two characters of the original field names.

It’s important to note that the Rename and Prefix keywords apply only to the RPG program within which they are coded. They do not affect the naming conventions used in the actual database. These keywords are simply a means of accommodating RPG requirements to differentiate record formats and field names.

Extdesc, Extfile, Extmbr

The Extdesc, Extfile, and Extmbr keywords serve to redirect the compiler or the program (or both) to a file other than the one named in the Dcl-f instruction, or to redirect the program to a specific member in a multiple-member file. This redirection is commonly called an override. The Extdesc keyword, which is valid only for externally described files, names a file that the compiler is to use to retrieve the record layouts for the file named in the Dcl-f instruction. For example, you can instruct the compiler to retrieve the record layout from a specific library that might not be in the compiler job’s library list:

The Extdesc override only occurs when you compile the program, not when you execute it. The Extfile keyword, though, overrides the filename at runtime, when the program executes it:

To override the file at compile time and at runtime, use both Extdesc and Extfile keywords:

Or, if the overrides are to the same file at both compile time and runtime, use the following:

Recall that a file member is a set of data within a database file and that source members store RPG code in a source file. Other database files also have members, though most database files are single-member files. But occasionally, an RPG application may need to process one or more members of a multiple-member file. By default, RPG processes only the first member it encounters in a file. You can use the Extmbr keyword on a Dcl-f instruction to override the file to a specific member instead: