The Specifics on Subfiles

According to IBM, a subfile is a group of records that have the same record format and are read from and written to a display station in one operation. As this definition suggests, a subfile is not a file; rather, it is a temporary place to store data of the same format to be used by a display file program.

Why Use Subfiles?

Figure 1.1 shows the typical use of a subfile. As you can see, subfiles are useful when you want to list multiple, like records on a display. A major benefit of subfiles is that you can define them so the number of displayed records exceeds the number of lines available on the screen, allowing the user to scroll, or page, through the data. This is usually the reason you would decide to use subfiles in your display program. Because of their ease of use, however, I deploy subfiles even when I think I will never display more than one screen, because they are easy to change if the data someday requires more than one screen.

In addition to simply displaying multiple lines of data, you can use subfiles and their multiple-line capabilities to add, change, and delete records very effectively. You can also use subfiles in a non-display manner, to create self-extending data structures and arrays in your RPG program. They work like multiple-occurrence data structures and arrays, except that instead of having to hard-code a number of elements large enough to hold the maximum number of entries, you can use subfiles. You start with a small number of entries and allow the number to expand dynamically, as your data expands.

Why Should You Care?

Haven't programmers been able to display data to a screen for years, without subfiles? Yes, but subfiles allow you to display lists of like data that can extend beyond one screen. They make it easier for you to create display applications, which, in turn, makes you more productive. Subfile programs are easy to write and maintain because much of the work is done for you in the Data Definition Specifications (DDS). Most of the time, you can change the characteristics of a subfile program without having to modify the RPG code driving it.

If that isn't enough, keep in mind that the ability to code subfiles is often the measure of an RPG programmer's worth. As an added benefit, when you're talking with a group of programmers at a users' group or technical conference, you can hold your head high, knowing that you're right up there with the rest of the subfile- savvy programmers.

Two DDS Formats Are Better Than One

As I stated earlier, most of the work in a subfile application is accomplished in the DDS. For every subfile you describe in your DDS, you're required to use two format types: a subfile record format (SFL) and a subfile control record format (SFLCTL). The subfile record format is used much as a record format is for a physical file. It defines the fields contained in a row of a subfile, describes the definition and attributes of those fields, and holds the actual data.

Unlike a physical file, however, a subfile record format is used only in memory, and only for the duration of the job. Once the program using the subfile ends, the data in that subfile is gone. Individual subfile records are read from, written to, and updated to the subfile by accessing the subfile record format in your program. The SFL keyword is required in your DDS to define a subfile record, just as the RECORD keyword is used for a typical display record format.

The subfile control record format describes the heading information for the subfile and controls how the subfile is going to perform. It's here that you define the size of the subfile, as well as the conditions under which the subfile will be cleared, initialized, displayed, and ended. The subfile control record format is unique because it controls aspects of a subfile in a way that other files aren't controlled. For example, you control the size of a physical file during compilation or by using the Change Physical File (CHGPF) command. You do not determine it in the DDS. Your program will operate the subfile control record format directly when it performs functions to the whole subfile, not individual records. Actions such as initializing, clearing, and displaying are accomplished in this fashion.

Four keywords are required in the subfile control record format:

1. The subfile control (SFLCTL) keyword identifies the subfile control record format, much as the record (RECORD) keyword identifies a typical display record format. The SFLCTL keyword also identifies the subfile record format that must immediately precede it.

2. The subfile size (SFLSIZ) keyword specifies the initial number of records the subfile may contain.

3. The subfile page (SFLPAG) keyword specifies the number of records that one screen of data may contain.

4. The subfile display (SFLDSP) keyword specifies when the subfile is displayed.

Note that the first requirement states that the SFLCTL keyword identifies the subfile record format that precedes it. Therefore, the SFL record format must immediately precede the SFLCTL format. The individual keywords available in each format can be placed in any order, but they must exist at the top of the format, before any constant or field definitions.

DDS and RPG Working as One

Once you code and compile the DDS for a subfile, you are ready to use that subfile in your RPG program. Your first three actions will be initializing, loading, and displaying your subfile. There are other things you can, and will, do to a subfile, but let's start with that foundation, and build up from there.

Before loading a subfile, you might want to clear or initialize it for use. Clearing or initializing takes effect when you write to the subfile control record format with the appropriate conditioning indicator set on, using the RPG WRITE operation. This isn't a requirement for the introductory load in your program, but as you create more complex subfile applications, you'll need to know the difference between clearing and initializing a subfile.

Let's return to the DDS for a moment. To clear a subfile, use the subfile clear (SFLCLR) keyword. This removes all records from the subfile. However, it does not remove them from the display until the next time the subfile is written to the screen by your program. This is different from the subfile initialize (SFLINZ) keyword, which will set all the records in your subfile to their default value. If you have no default value set in your DDS, numeric fields will...