Using IBM i? Need to create Excel, CSV, HTML, JSON, PDF, SPOOL reports? Learn more about the fastest and least expensive tool for the job: SQL iQuery.
The File Specification
To declare a file in an RPG IV program that can read from, written to, or updated, requires the File Description Specification, often referred to as the "File spec" or more simply the "F spec".
A separate File spec defines each file to the RPG IV program. File names, open options, access methods, and device types are specified there. In addition, the File spec accepts keywords that control additional attributes about the file declaration. Things like changing a record format name, assigning the input buffer to a data structure, and controlling whether or not RPG IV automatically opens the file when the program is evoked.
Externally described files require less coding than program described files. The compiler imports most of the attributes of externally described files so you do not need to specify things like record length or field location and data-type. Program described files on the other hand, require that all this information is hand coded into the File specification. Both of these type of File specs are illustrated below:
.....FFileName++IFEASFRlen+LKeylnKFDevice+.Functions++++++++++++++++++++++++++++
FCUSTMAST IF A E K DISK
FCUSTMAST IF A F 65 4AIDISK
The following is the layout of the RPG IV File Description Specification.
0 0 1 2 3 4 5 6 7 8
1....6...0... v ...0... v ...0... v ...0... v ...0... v ...0... v ...0... v ...0
.....FFileName++IFEASFRlen+LKeylnKFDevice+.Functions++++++++++++++++++++++++++++
Let's look at the components of the File Description Specification:
Position 6 must be the letter "F" to indicate that this is an RPG IV File Description Specification. Upper or lower case is ignored, as it is throughout RPG IV.
Positions 7 to 16 contain the name of the file being declared. Up to a 10-position File name may be specified. AS/400 object names must be 10 positions or less, so this is currently adequate space.
Position 17 indicates how the file will be treated in the program. Input, Output, Update or, if a Display (workstation) file Combined. The follow is a list of the valid entries for position 17 along with their purpose:
| Open Attribute | Description |
|---|---|
| I | The file is open for Input |
| O | The file is open for Output |
| U | The file is open for Update (this allows existing database records to be changed and written back to the file). |
| C | For Workstation Files only, Indicates that the workstation file is open for Input and Output processing. |
Position 18 is used to indicate if the RPG Logic Cycle is used to process the file in this program. While some legacy applications continue to use this capability, most programs written in the last 20+ years will have an "F" specified for position 18. Any other value indicates that the RPG Logic Cycle will process the file. So use and "F" (Full Procedural File Control) in column 18 when defining your files.
Position 19 is used only when position 18 is not "F". A value of "E" in position 19 indicates that the RPG Logic Cycle should process all the records in this file before automatically "setting on LR" to end the program. Again, the RPG Logic Cycle is no longer the standard.
Position 20 is a continuation of Position 17. Specify the letter "A" in position 20 to indicate that a file declare for Input (an "I" in position 17) is also output capable. For example, the following declaration opens the CUSTMAST file for Input / Output processing, or as its conventionally called in RPG, "input-Add":
.....FFileName++IFEASFRlen+LKeylnKFDevice+.Functions++++++++++++++++++++++++++++
FCUSTMAST IF A E K DISK
Positions 21 through position 33 are not used for Externally Described Files, so will skip those for this lesson.
Position 22 must contain the letter "E" when an Externally Described file is being declared. Positions 23 through 22 must be blank for Externally Described Files. To declare a Program Described file, the letter "F" is specified in position 22.
| Format | Description |
|---|---|
| E | Externally Described |
| F | Program Described |
Position 34 is used to indicate the record access type for processing the file. Specify the letter "K" to indicate keyed processing is requested. This causes all RPG IV I/O operations to use the file's primary key to access to file. The only other valid value in this position is a blank, which means sequential processing is requested. Sequential process causes all RPG IV I/O operation to process the file sequentially and all random access input operations (such as CHAIN) to retrieve records by their relative record number. The other available record access types include:
| Format | Description |
|---|---|
| Externally Described Files: | |
| K | Externally described keyed (random) access. |
| blank | Sequential processing is used. |
| Program Described Files Only: | |
| A | Alphabetic keyed access |
| P | Packed decimal keyed access |
| G | |
| D | Date field keyed access |
| T | Time field keyed access |
| Z | Zoned Decimal field keyed access |
| F | Floating Point field keyed access |
Position 35 is left blank for Externally Described Files. For Program Described File, the letter "I" is used to indicate "keyed" access (the "I" stands for "Indexed").
Positions 36 to 42 contain the device for the file. For database files the only value specified is DISK. The full list of valid Device types include the following:
| Device Type | Description |
|---|---|
| DISK | Database File |
| PRINTER | Print File |
| WORKSTN | Workstation File (may be a Display or Telecommunications file) |
| SPECIAL | A user-written I/O driver (i.e., program) is provide to process data when READ/WRITE operations are performed. |
| SEQ | Sequentially Processed File (rarely used) for reading directly from a Tape device or legacy 80-column card hoppers) |
Position 43 is reserved and must be blank.
Position 44 through 80 contain option device keywords. These keywords are dependent on the type of Device specified in positions 36 to 42. A list of the most commonly used keywords is featured on the next page in this lesson.
Let's look at a few example Externally Described File Declarations:
Open for Input-only Keyed (randon-access) processing
6...1... v ...2... v ...3... v ...4... v ...5... v ...6... v ...7... v ...8 FFileName++IFEASFRlen+LKeylnKFDevice+.Functions++++++++++++++++++++++++++++ Fcustmast IF E K Disk
Open for Input-only Sequential Processing
6...1... v ...2... v ...3... v ...4... v ...5... v ...6... v ...7... v ...8 FFileName++IFEASFRlen+LKeylnKFDevice+.Functions++++++++++++++++++++++++++++ Fcustmast IF E Disk
Open for Output-only Sequential Processing
6...1... v ...2... v ...3... v ...4... v ...5... v ...6... v ...7... v ...8 FFileName++IFEASFRlen+LKeylnKFDevice+.Functions++++++++++++++++++++++++++++ Fcustmast O E Disk
Open for Input-Output Sequential Processing
6...1... v ...2... v ...3... v ...4... v ...5... v ...6... v ...7... v ...8 FFileName++IFEASFRlen+LKeylnKFDevice+.Functions++++++++++++++++++++++++++++ Fcustmast IF A E Disk
Open for Update, Keyed Processing
6...1... v ...2... v ...3... v ...4... v ...5... v ...6... v ...7... v ...8 FFileName++IFEASFRlen+LKeylnKFDevice+.Functions++++++++++++++++++++++++++++ Fcustmast UF E K Disk
Open for Update-Output, Keyed Processing
6...1... v ...2... v ...3... v ...4... v ...5... v ...6... v ...7... v ...8 FFileName++IFEASFRlen+LKeylnKFDevice+.Functions++++++++++++++++++++++++++++ Fcustmast UF A E K Disk
The technique to open a WORKSTN or PRINTER file is less diverse. You typically see only one or two variations of these types of file declarations in RPG IV:
Declare a Display File
6...1... v ...2... v ...3... v ...4... v ...5... v ...6... v ...7... v ...8 FFileName++IFEASFRlen+LKeylnKFDevice+.Functions++++++++++++++++++++++++++++ Fcustmaint CF E WORKSTN
Display files are, with rare exceptions, open for Combined ('C' in position 17) processing. You almost never see a program-described WORKSTN file in RPG IV, and certainly no one in the last 20 or 30 years has had any reason to use program-described WORKSTN files.
Legacy applications often include the INFDS keyword, while more contemporary applications often include the INDDS (indicator data structure) keyword.
The INFDS keyword provides some useful information about the workstation/display file. Information such as current cursor location, record format just processed, and subfile record number are a few of the more common ones. Most of the data returned to the program in the INFDS (sometimes called WSDS when referring to the INFDS for a WORKSTN file) can be extracted from keywords inserted into the actual Display File DDS itself.
The INDDS keyword is used to route the state of indicators used in the Display File DDS into a data structure so that they do not:
- Interfere with existing indicators already in use by the program.
- Allow you to avoid numeric indicators entirely by assigning meaningful names to those indicates via data structure subfield names.
Declare an Externally Described Printer File
6...1... v ...2... v ...3... v ...4... v ...5... v ...6... v ...7... v ...8 FFileName++IFEASFRlen+LKeylnKFDevice+.Functions++++++++++++++++++++++++++++ Fcustmaint O E PRINTER OFLIND(*INOF)
Printer files are require the assignment of what's called an Overflow Indicator. This indicator is automatically set on when the program is about to print onto a line that is beyond the number of maximum lines on the page. This line number is called the Overflow Line Number and may be set using the OFLLIN keyword, but often simply defaults to whatever is specified in the external printer file description. The INDDS keyword and data structure may also be used for PRINTER files to avoid indicator conflict with those used in the program.
Declare a Program Described Printer File
6...1... v ...2... v ...3... v ...4... v ...5... v ...6... v ...7... v ...8 FFileName++IFEASFRlen+LKeylnKFDevice+.Functions++++++++++++++++++++++++++++ Fcustmaint O F 132 PRINTER OFLIND(*INOF) OFLLIN(80)
Program Described Printer files are very common in RPG IV. This is due to the fact that almost all legacy program written before 1990 used program-described printer files. Since then, most new code is taking advantage of externally described print file. And even more recently many of the shorter, customized printed reports are being displaced by routing the output normally destine for printer files, to XML, Microsoft Excel, or even PDF files.
# # #