FILE SPECIFICATION

The file specification is used to declare each file used by the program (except for SQL tables and views, which are accessed through SQL statements). Each file must have its own file specification. Additional information about the file is optionally specified with one or more file keywords.

The two basic file types in RPG are program-described files and externally described files. With program-described files, input and output fields are explicitly defined in the source. With externally described files, the input and output field definitions are inserted into the program by the compiler. Most applications written today use externally described files. Figure 2.2 illustrates the format of the file specification. Table 2.5 lists the file description specifications and Table 2.6 lists the file keywords.

Table 2.5: File Description Specification Summary

Column	Title	Values	Description
6	Form type	F	Identifies the statement as a file description specification.
7 – 16	File name	Blanks	The statement is a file continuation.
		File name	The name of a file to be used by this program.
17	File type	I	The file is opened for input processing.
		O	The file is opened for output processing.
		U	The file is opened for update (read, change, delete) processing.
		C	The file is opened for combined (read, write) processing. Valid for WORKSTN files only.
18	File designation	Blank	The file is an output file. Blank is the only valid entry for output files.
		P	The file is the primary file. There can be only one primary file in an RPG program.
		S	The file is a secondary file. There can be 0, 1, or more than one secondary file in an RPG program.
		R	The file is a record address (ADDROUT) file.
		T	The file is a pre-runtime table. The file is "read into" the array specified on the extension specifications when the program is called.
		F	The file is a full-procedural file. The file is processed only through procedural RPG file operations, such as READ and WRITE in the calculation specifications. The RPG cycle does nothing more than automatically open and close the file.
19	End of file	Blank	If all files contain a blank entry in this column, then all records in all files are processed before the RPG cycle sets on the LR indicator.
		E	When all the records from this file have been processed, the RPG cycle sets on the LR indicator. If more than one file uses this option, all records from each file containing the end-of-file indication are processed before the RPG cycle sets on the LR indicator. The end-of-file indication applies only to files specified as primary or secondary. It does not apply to full procedural files.
20	File addition	Blanks	For input and update files (file type I or U), no records can be added (i.e., written) to the file. The compiler generates an error if WRITE or EXCEPT with ADD operations are used.
		A	For input and update files (file type I or U) the WRITE and EXCEPT with ADD operations are allowed. This allows new records to be added to the file. For output files, the entry in this column is ignored.
21	Sequence	Blank or A	The sequence for matching record fields is ascending order.
		D	The sequence for matching record fields is descending order.
22	Format	F	The file is program described. Input specifications are used to define the record format for this file.
		E	The file is externally described. The RPG compiler imports the record format for the file.
23 – 27	Record length	Blank	Valid when the file is an externally described file. The compiler imports the record length when it is unspecified.
		1 to 32,766	The length used by RPG for the file. The actual record length may be different from this value; RPG pads or truncates the record as required.
28	Mode of processing	Blank	The mode of processing is controlled by the entries in the file designation and the record address type.
		L	The mode of processing is sequential within limits; meaning the file is an ADDROUT file.
29 – 33	Length of key fields	Blanks	The key is established outside the RPG program or the file is not keyed.
		1 to 2,000	The length of the key for a program-described file.
34	Record address type	Blank	The file processing (access) is sequential or by relative record number.
		A	The key to the file is a character value (for program-described files only).
		P	The key to the file is a packed decimal value (for program-described files only).
		G	Graphic keys (DBCS keyed database file).
		K	Keyed file (for externally described files only).
		D	The key to the file is a date value.
		F	The key to the file is a floating-point value.
		T	The key to the file is a time value.
		Z	The key to the file is a timestamp value.
35	File organization	Blank	The file is not keyed (for program-described files). For externally described files, this entry must be blank.
		I	The program-described file is "indexed"; in other words, it's a keyed file.
		T	The program-described file is a record address file (ADDROUT) file containing relative record numbers to be used for sequencing file input.
36 – 42	Device type	DISK	The file is a database (disk) file.
		PRINTER	The file is a printer file and can be written to.
		WORKSTN	The file is an interactive workstation.
		SEQ	The file is a sequential file that is processed by READ, WRITE, OPEN, and CLOSE operations.
		SPECIAL	The file is processed using a special device "driver." A device driver is a program (such as another RPG program) that handles the input and output requests from this program. The name of the device driver program is specified with the PGMNAME keyword.
43			Not used.
44	File keywords	Blank	Normal file processing.
		Keyword	File keywords. See Table 2.6 for a list of valid keywords.

Table 2.6: File Description Keyword Summary

Keyword	Parameters	Description
BLOCK	*YES	Record blocking is performed if the proper conditions are met for the operating system. Use type keyword option to override the default selected by the RPG compiler.
	*NO	No record blocking is performed on the file.
COMMIT	Commit status	Activates commitment control and the COMMIT and ROLBK operations in the program. Valid options are '1' and '0'. An indicator or other character field can be specified. The commit status field value is tested when the file is open.
DATFMT	Format separator	Sets the default date format for the fields in the file. This includes the keyfields (if any). The separator is used to edit the date on output operations and when date literals are moved to, or compared with, date fields in this file.
DEVID	Device ID	Device ID being processed. The field name specified for this keyword is automatically defined as a 10-position character field. Typically, this keyword is not used in RPG IV.
EXTIND	*INUx	Controls the file open. The file is automatically opened when the program is called and the corresponding UPSI indicator is ON. The file is not open if the indicator is OFF when the program is called. Valid range for x is 1 to 8. See also USROPN keyword.
EXTFILE	Runtime file name	Identifies the name of the file to be open at runtime. This may be a different file name from that specified in columns 7 to 16. If the EXTFILE keyword is not specified, the file name specified in columns 7 to 16 is used at runtime. The runtime file name may be a literal or a field name. If a field name is used then its value must be specified before the file is open. This can be accomplished through several methods, including but not limited to: A value from entry parameter An initial value A USROPN keyword. This allows the file name to be specified on a controlled basis, before the file is opened. The syntax for the file name is as follows: {LIBRARY/}FILE The file name may be a qualified or unqualified file name, and if a field is specified, the file name must be left justified within that field, and must be specified in uppercase letters. The library name is optional, and if not specified, the library list (*LIBL) is used. The only special value that may be used for the library name is *LIBL. Note that when EXTFILE is used, any overrides applied to the file name specified in columns 7 to 16 of the File specification are ignored. Overrides applied to the file name specified in EXTFILE keyword are processed like normal.
EXTMBR	Runtime member name	Identifies the name of the member to be open at runtime. The member name must be in the correct case. For example, the keyword EXTMBR(mbrname) uses the variable mbrname. If that variable contains the name 'custmast', the member will not be found. Instead, the member name should have been specified in all upper case as follows: 'CUSTMAST'.
FORMLEN	Page size	Specify the number of lines per page for the PRINTER device file. The valid range is 1 to 255 lines. See FORMOFL and OFLIND keywords.
FORMOFL	Overflow line	Specify the line number that triggers the overflow indicator. The value specified for this keyword must be less than or equal to the value specified for the FORMLEN keyword. See FORMLEN and OFLIND keywords.
IGNORE	Format1 [: format2...]	The record format name(s) specified for the externally described file is not imported into the program by the compiler. Multiple names can be specified, separated by a colon.
INCLUDE	Format1 [: format 2...]	The record format names specified for the externally described file are imported into the program by the compiler. When an INCLUDE keyword is specified, only format names that appear in the INCLUDE keyword are imported; all other formats are ignored. A colon separates multiple names.
INDDS	Data structure	The name of a data structure that is associated with the PRINTER or WORKSTN device file. The positions in this data structure correspond to the standard 99 numeric RPG indicators. For example, position 1 of the data structure corresponds to indicator *IN01 as used by the device file. This data structure is always 99 positions in length. Use this data structure to assign more readable named indicator variables to the traditional 99 numeric indicators.
INFDS	Data structure	The name of a data structure that is associated with the file description specification. The data structure receives status and error information about the file.
INFSR	Subroutine	The name of the RPG subroutine that is called when an exception/error occurs on the file being declared.
KEYLOC	Key position	The location (record position) of the key for the file being declared. Valid range is 1 to 32,766, but must not exceed the record length for the file, minus the key length. This entry is ignored for programs running on the IBM AS/400.
MAXDEV	*ONLY	A single device file can be allocated to the program.
	*FILE	The maximum number of devices that can be allocated to the program is retrieved from the WORKSTN device file when the file is open.
OFLIND	*INxx	Overflow indicator is set on when the line specified by the FORMOFL keyword is printed. Valid entries for program-described PRINTER files are *INOA to *INOG, and *INOV as well as any valid numeric indicator. For externally described printer files, indicators *IN01 to *IN99 are supported. See FORMOFL and FORMLEN keywords.
PASS	*NOIND	This keyword and its required entry of *NOIND indicates that no indicators are transferred to the program through the internal file buffer. Instead, the program contains input and output fields (identified as *INxx, where xx is the indicator being passed) to pass the indicators.
PGMNAME	Program	For SPECIAL device files, this name identifies the program that is called to perform file input/output processing when a READ, WRITE, UPDATE, etc., operation is used on the file. See SPECIAL device files.
PLIST	Parameter-list	For SPECIAL device files, this keyword identifies a parameter-list containing optional parameters that are passed to the device driver named in the PGMNAME keyword. The parameters from the parameter list are added (by the compiler) to the following parameter list:
		OPTION	CHAR(1) /* Operation */ O = Open the file C = Close the file R = Read from the file W = Write to the file D = Delete the current record U = Update the current record
		Status	CHAR(1) /* Return code */ 0 = Normal completion 1 = End or beginning of file 2 = Exception/error occurred
		Error	ZONED(5,0) /* Error code */ Returned to the *RECORD subfield of the INFDS data structure for the file.
		Area	CHAR(*) /* Data from, or for, the record */ The data for the record is placed into this parameter and returned to the input record format of the SPECIAL device file. The actual length of this parameter, as passed to the program, is equal to the file length specified for the SPECIAL device file.
		RPG automatically generates this parameter list in the program that contains the SPECIAL device file. In the program being used as the SPECIAL device file's I/O routine, however, this parameter list must be specified.
PREFIX	Prefix [: replace count]	For externally described files, the prefix is used to automatically rename all fields in the file. The prefix is appended to the front of the field name for each field in the file's record format. If the prefix needs to contain special characters, such as the period, it must be specified in all uppercase letters and enclosed in quotes. The replace count controls whether or not the first replace-count characters of each field name are trimmed from the field name before the automatic rename occurs. For example, if all the fields in the file begin with CST (as in CSTNAM, CSTNBR, CSTADR), the PREFIX keyword's replace count can be used to remove the leading three characters from each field. In this case, a PREFIX keyword specified as: PREFIX(CM_ : 3) would rename the above fields, as follows: CM_NAM, CM_NBR, CM_ADR The total length of a renamed field name cannot exceed the maximum length for an RPG IV field name.
PRTCTL	Data struct [:*compat]	Specify the name of the data structure that will be used as the printer-control data structure. The printer spacing, skipping, and overflow information are stored in this data structure. The optional parameter *COMPAT causes the data structure to be compatible with RPG III. See PRTCTL data structure. Standard PRTCTL data structure: .....DName+++++++++++ETDSFrom+++To/L+++IDc D PrtCtl DS D SpaceB 3A D SpaceA 3A D SkipB 3A D SkipA 3A D CurLine 3S 0 PRTCTL data structure with *COMPAT: .....DName+++++++++++ETDSFrom+++To/L+++IDc D PRTCTL_RG3 DS D SPCBFR 1A D SPCAFT 1A D SKPBFR 2A D SKPAFT 2A D CURLIN 3S 0 Note that there is no entry for total number of pages. Since writing to the printed page is serial in nature, there is no way to automatically determine the page count without first printing all pages.
RAFDATA	Filename	Names the input file or update file that is associated with this record address file. The filename that appears in the parentheses of this keyword is controlled with this file.
RECNO	Recnum-field	For database files that use relative record-number processing, or for output files that are referenced by a random WRITE calculation or are used with ADD on the output specifications, specify the name of the field that is to contain the relative record number of the file. Typically, this keyword is not used in RPG IV.
RENAME	External-name : new-name	The externally described file's external-name record format is renamed to the new-name.
SAVEDS	Data struct	The name of a data structure is saved before each input operation to a WORKSTN device file. Typically, this keyword isn't used in RPG IV.
SAVEIND	Saved-indicator-count	Number of indicators to save. Typically, this keyword isn't used in RPG IV.
SFILE	Format : relno	The name of the subfile detail record format that is being used in this program. The relno parameter is a field name that is used as the subfile's relative record number. You set the value in this field for a CHAIN or WRITE operation to the subfile. RPG sets this field when you perform a READC (read changed subfile record) or a CHAIN (random get) operation.
SLN	Starting-line	Starting line number. The starting-line field is used to control the line number to which WORKSTN display device files send their output. RPG automatically defines the field as a two-position numeric field with zero decimal places. Note The DDS keyword SLNO(*VAR) must also be specified in the DDS for the workstation file.
TIMFMT	Format separator	Sets the default time format for time data-type fields in the file. This includes the keyfields for the file. The separator identifies the symbol to be used when the field is output or when a time literal is moved to, or compared with, the time fields in this file.
USROPN		User-controlled open. Causes the program to avoid automatically opening this file when the program is called for the first time. When this keyword is used, the file must be opened through some other method, such as with the OPEN operation or by an external file management command.

 .....FFileName++IFEASFRlen+LKeylnKFDevice+.Functions++++++++++++++++++++++++++++ 

Figure 2.2: File specification ruler.