The FILELIST and FILELISTEND constructs define the beginning and ending points of a group of IFILE and/or AFILE variables.
The first IFILE or AFILE declaration in the FILELIST is the primary file. Any subsequent IFILE or AFILE declarations are secondary files.
The FILELIST may not be empty.
A FILELIST is limited to thirty (30) files.
The label specified for the FILELIST is required and references the file group in an OPEN, CLOSE, WRITE, UPDATE, or DELETE instruction. When a FILELIST is used in an OPEN instruction, all of FILELIST files must have a NAME parameter declared.
The following are instructions may be used with a FILELIST: OPEN, CLOSE, DELETE, WRITE, and UPDATE.
Each FILELIST defined without the ^ qualifier must have a terminating FILELISTEND statement that indicates the end of the FILELIST group. If the ^ is specified, the FILELIST is a pointer and the FILELISTEND statement is not allowed.
A FILELISTEND statement without a prior FILELIST statement declaration is not allowed.
If the FILELIST is defined as Global, all included file variables must also be defined as Global variables.
If a FILELIST is declared as Common, all included file variables must also be declared as Common.
Nesting of FILELIST/FILELISTEND constructs is not allowed.
All of the files in a FILELIST must be managed files or they must all be not managed. Mixing managed and non-managed files causes a runtime execution error.
When a FILELIST operation is executed, the file group is validated to ensure the following:
All of the files are opened.
All of the files are using the same text data file.
All of the files are managed or non-managed.
All of the files are FIXED or not FIXED.
When the files are declared as FIXED, all of the files must be defined with the same record length.
When the files are declared as VARIABLE or COMPRESSED, each of the secondary files must have a maximum record length greater than or equal to the primary file.
When using a PREPARE or OPEN for any file specified in a FILELIST, a valid key specification must be available for the file. Note that the IFILE PREPARE operation was modified to allow valid key specifications.
A valid ISAM key specification is the same as defined for the INDEX utilities. This can include the actual keys (i.e., 1-5,...) and can also include the 'Pnnn...' options for record select for keys. Any other index options that are encountered are ignored.
If an IFILE OPEN instruction is executed and the ISAM file does not have any key specifications, an attempt is made to extract the key data directly from the command line string in the ISAM file header. If the command line string is not present, an I23 error is given. Once the key data has been extracted, the ISAM file header is updated to provide the keys and record selection data for subsequent OPEN operations. Note: This means that an IFILE OPEN can use existing ISAM files for FILELIST operations without re-indexing the files.
If an IFILE PREPARE instruction is performed for an IFILE in a FILELIST, the key specifications must be supplied. If no key specifications are provided, an I23 error is given.
It is not valid to DELETE, INSERT, UPDATE, or WRITE using individual AFILE or IFILE declared in a FILELIST. All operations that modify a file declared in a FILELIST must use the FILELIST name.
FILELIST does not work with RMS files.
The first file defined in a FILELIST should not be created with the primary key option.
IFILEs using the primary key option must use the standard primary key (P{nn}{=|#}{c}) format. If an ISI is generated using the alternate primary key specification (P{type}"{col}{func}{'string'}") option, the ISI file cannot be included in a FILELIST declaration. Otherwise, an I23 subcode 40 error is given for any FILELIST WRITE or UPDATE operation executed. Note also that:
The
alternate primary data is not available in an ISI header. Prior to 8.5C, the ISAM
keys for this form of an ISI file could be invalid after a FILELIST WRITE/UPDATE
operation.
Use
of the primary key specification (P{nn}{=|#}{c}) for generation of an ISI file has always worked for an
IFILE included in a FILELIST declaration
before and after changes made for 8.5C.
