The File Description Specification (FILE) command is used in a CL program to include record format and field definitions into the CL source program being compiled. There is no limit on the number of FILE commands that are allowed in a CL program. There is a limit of 1000 files per activation group that can be concurrently open using the Open File for Processing (OPEN) command.

The FILE command requires that you provide the name of a File ID. This File ID is then referenced by other CLF commands such as Open File for Processing (OPEN) to open the file, Read a Record (READ) to read from the file, etc. Optionally you can also specify the name of a file (database physical or logical, display, printer, ICF, etc); the file record formats to be used by the program; how storage for the record formats and record fields is to be managed, and how field and record format names might be modified as they are being declared.

When using the precompiler multiple FILE commands can reference the same file and record format(s) so long as:

• a unique File identifier (FILEID) is specified and
• FLDSTG(*AUTO) is specified

Multiple FILE commands can also reference the same file and record format(s) with FLDSTG(*DEFINED) so long as:

• a unique File identifier (FILEID) is specified and
• the values specified for the Name modifier (NAMMDF) parameter are unique

Up to 32 record formats can be specified per FILE command.

When FLDSTG(*AUTO) is used and

• the same field name is defined in more than one record format and
• no field name modification is done using the Name modifier (NAMMDF) parameter

then the first declare of the field is used to determine the attributes of the field. If FLDSTG(*DEFINED) is used, without NAMMDF modifications of the field name, then the program will not create successfully due to the field name reuse.

Any CL variable defined in the program by a DCL, DCLF, or GENFFDCLF command, with the same name as a FILE created field, should be defined in the CL source prior to the FILE command. In addition FLDSTG(*AUTO) must be specified.

Restrictions:

• The FILE command must be treated as a declare command. All declare commands (INDS, DCLFKSCLF, DCL, COPYRIGHT, DCLF, and DCLPRCOPT) must follow the PGM (Program) command and must precede all other commands in the program. The various types of declare commands can be intermixed in any order.
• This command can only be used when the CL source program is compiled using either the Create Bound CLF Program (CRTBNDCLF) command, the Create CLF Module (CRTCLFMOD) command, or the Create CLF Program (CRTCLFPGM) command. The Generate File Field Definition (GENFFDCLF) command can be used to generate a stand-alone definition of the file, record format, and field definitions without the use of the precompiler commands.
• The referenced file must exist when the program is compiled.
• If the file is changed and Record format level check (LVLCHK) *YES is specified on an Open File for Processing (OPEN) command referencing this FILEID the CL program must be recompiled to match the new file description.
• You must have *OBJOPR authority to the file specified for the File (FILE) parameter, and *USE authority to the library that contains the file.

Parameters

File identifier (FILEID)

Specifies the file identifier that will be used by other CLF commands. This parameter is used by CLF commands to identify the file to be processed by other CLF commands.

This is a required parameter.

simple-name

Specify a name that will be used by subsequent CLF commands.

File (FILE)

Specifies the file to be used to determine the record formats and fields to be associated with the FILEID.

Single values

*FILEID

The value specified for the FILEID parameter will be used as the file name.

Qualifier 1: File

name

Specify the name of the file.

Qualifier 2: Library

*LIBL

All libraries in the library list are searched until the first match is found.

*CURLIB

The current library for the job is used to locate the file. If no current library entry exists in the library list, QGPL is used.

name

Specify the library where the file is located.

Record format (RCDFMT)

Specifies the names of one or more record formats contained in the file. These record formats can be used by commands such as Read a Record (READ), Create New Records (WRITE), Modify Existing Record (UPDATE), and Delete Record (DELETE).

You can specify up to 32 values for this parameter.

*ALL

Every record format in the file, up to a maximum of 32, is to have the record format and associated fields declared as program variables.

*NONE

No record format, or associated fields, are to be declared as program variables. File level check information is declared as a program variable. The file can be used with CL variables declared by other DCL, DCLF, FILE, or GENFFDCLF commands in the CL program.

name

Specify the name of the file record format that is to be declared as a CL variable. Fields associated with the record formats listed will also be declared as CL variables.

Field storage (FLDSTG)

Specifies how storage is to be managed for fields associated with record formats of the file.

*AUTO

A CL variable is declared and allocated for each field. Field data is moved from the record format storage to the storage associated with each field.

Having common fields declared and allocated once within the CL program can simplify the sharing of data when using fields of the same name from multiple files.

*DEFINED

A CL variable is declared for each field. No storage is allocated for the field within the CL program. The declared CL variable is based on the storage associated with the record format variable.

When working with only one file, or files that do not share common field names, *DEFINED field storage can provide a small performance advantage over *AUTO field storage.

Name modifier (NAMMDF)

Specifies any CL variable name modifications that are to be done with the record format and field names associated with the file. This parameter can be used to provide unique instances of CL variables where fields share the same name. All CL variable names will be prefixed with an ampersand (&).

When necessary, in order to provide unique CL variable names in the compiled CL program, additional name modifications will be made to the name of the record format or field name. These modifications will be in addition to the characters specified for the NAMMDF Identifier element.

When using FLDSTG(*DEFINED)

• if the file and record format names are the same, CLF will append the value '_R' to the end of the record format name
• if a field within a record format is used for both input and output, and the location of the field within the record format is different for input and output, then CLF will append the value '_I' to the end of the field name for input and append the value '_O' to the end of the field name for output

If the resulting CL variable name is greater than 11 characters in length, trailing characters of the original record format or field name will be truncated.

Element 1: Identifier

*NONE

The record format and field names associated with the file will not be modified.

character-value

Specify a modifier that should be used for record format and field names generated for the file. The modifier can be one or two characters in length. The characters that are valid depend on the value specified for the Location element.

Element 2: Location

*PREFIX

The name modifier is used to prefix the field name. The CL variable name generated will be the field name prefixed with an ampersand (&), the value specified for the NAMMDF parameter, and an underscore (_). For example, if a field name of EMPSTS is found in the file and NAMMDF(B *PREFIX) is specified the generated CL variable name will be &B_EMPSTS.

The first character of the name modifier must be alphabetic. The second character, if specified, must be alphanumeric or one of the special characters, * or _. Both the * and the _ indicate that the command should generate a second character name modifier for each record format processed. When an * is specified the command will start with the letters A through Z followed by the numeric values 1,2,..9,0 when generating the second character. When a _ is specified the command will start with the numeric values 1,2,...9,0 followed by the letters A to Z.

If the length of the generated prefix plus the length of the field name exceeds 11 characters then trailing characters of the field name will be truncated.

*SUFFIX

The name modifier is used to suffix the field name. The CL variable name generated will be the field name prefixed with an ampersand (&). Following the field name will be an underscore (_) and the value specified for the NAMMDF parameter. For example, if a field name of EMPSTS is found in the file and NAMMDF(B *SUFFIX) is specified the generated CL variable name will be &EMPSTS_B.

The first character of the name modifier must be alphanumeric. The second character, if specified, must be alphanumeric or one of the special characters, * or _. Both the * and the _ indicate that the command should generate a new second character name modifier for each record format processed. When an * is specified the command will start with the letters A through Z followed by the numeric values 1,2,...9,0. When a _ is specified the command will start with the numeric values 1,2,...9,0 followed by the letters A to Z.

Variable field length support (VFLSPT)

Specifies how database variable-length fields are to be declared within the CL program. This keyword only applies to variable-length character and graphic database fields.

*VARLEN

Variable-length fields are to be defined as two distinct fields. The length attribute of the variable-length field can be accessed using the Retrieve Variable Field Length (RTVVFLCLF) command. The Set Variable Field Length (SETVFLCLF) command can be used to set the length attribute of the variable-length field.

The data portion of the field is defined as type *CHAR with a length equal to the field's defined maximum field length. The data is padded on the right with blanks to the field's maximum defined field length.

*FIXED

Variable-length fields are to be defined as one field of type *CHAR with a length equal to 2 bytes plus the maximum field length. The first two bytes of the CL variable contain the length of the data as a 2-byte integer value. The remaining bytes contain the data associated with the field. This data is padded on the right with blanks to the field's maximum defined field length.

VFLSPT(*FIXED) is compatible with the support for variable-length fields provided with the DCLF command when specifying ALWVARLEN(*YES).

OS target release (TGTRLS)

Specifies the release of the operating system that you intend to use the CLF product on. The earliest release that is supported by the CLF product is V5R4M0.

When specifying the target-release value, the format VxRxMx is used to specify the release, where Vx is the version, Rx is the release, and Mx is the modification level. For example, V5R4M0 is version 5, release 4, modification 0.

*CURRENT

The level of CLF function to be used is based on the release of the operating system currently running on your system. The functions can also be used on a system with any subsequent release of the operating system installed.

*PRV

The level of CLF function to be used is based on the previous release, with modification level 0, of the operating system currently running on your system. The functions can also be used on a system with any subsequent release of the operating system installed.

character-value

Specify the release in the format VxRxMx. The functions can be used on a system with the specified release or with any subsequent release of the operating system installed.

Examples for FILE

Example 1: Declare of File in a Specific Library

    File       FileID(VC2EMP) File(VC2CLF/VC2EMP)

All record formats, fields, and indicators associated with the file VC2EMP in library VC2CLF are automatically declared as variables within the CL program. The CL variables that are associated with fields of VC2EMP are declared as FLDSTG(*AUTO).

Example 2: Modifying Field Names

    File    FileID(VC2EMP) NamMdf(A)

All record formats, fields, and indicators associated with the file VC2EMP are automatically declared as variables within the CL program. The VC2EMP file is located using the job's current library list. The CL variables that are associated with fields of VC2EMP are prefixed by the constant '&A_'. For instance database fiele EMPNBR is now the CL variable named &A_EMPNBR.

Example 3: Name Modification with Multiple Record Formats

    File       FileID(MYVIEW) File(VC2DPTEMPL) NamMdf(B*)

All record formats, fields, and indicators associated with the file VC2DPTEMPL are automatically declared as variables within the CL program. The VC2DPTEMPL file is located using the job's current library list. Within the program the file will be known as 'MYVIEW'.

The VC2DPTEMPL file is a logical file with two record formats. The first format, DPTRCD, is based on the physical file VC2DPT. The second format, EMPRCD, is based on the physical file VC2EMP. The CL variables associated with the file are to be modified using the NAMMDF of 'B*'. This name modifier causes CL variable names associated with the first record format to be prefixed by the constant '&BA_'. For instance the field DPTID of record format DPTRCD will be named &BA_DPTID. CL variable names associated with the second record format will be prefixed by the constant '&BB_'. For instance EMPNBR of the EMPRCD record format will be declared as &BB_EMPNBR. This name modification will continue for the number of record formats that are to be declared within the CL program.

Example 4: Name Modification with Selected Record Formats

    File       FileID(MYVIEW) File(VC2DPTEMPL) +
                 RcdFmt(EMPRCD) NamMdf(B*)

Only the fields and indicators associated with record format EMPRCD in the file VC2DPTEMPL are automatically declared as variables within the CL program. The VC2DPTEMPL file is located using the job's current library list. Within the program the file will be known as 'MYVIEW'. Field names for record format EMPRCD defined fields will be prefixed by the constant '&BA_'.

Error messages for FILE

*ESCAPE Messages

VC25001

RCDFMT(*ALL) cannot be specified with any other values for the RCDFMT keyword.

VC25002

Unexpected failure accessing record format names.

VC25003

Record format &1 not found in file &2 of library &3.

VC25004

Unexpected failure accessing field names.

VC25005

Translation error found.

VC2500D

Invalid name modifier (NAMMDF) value specified.

VC25015

Invalid name modifier (NAMMDF) value specified.

VC25016

RCDFMT(*NONE) cannot be specified with any other record format values.

VC2501D

Operating system target release of &1 is not supported.

VC25035

NAMMDF special value &1 does not support greater than 36 record formats.

VC25036

&1 command cannot access file &4/&3.

VC25061

The length of record format &1 of file ID &2 exceeds &3 bytes.

VC29002

Function did not complete. See previously listed messages related to possible user errors.

VC29003

Function did not complete. See previously listed messages for possible cause.

VC29004

Function did not complete. See previously listed messages for possible cause.

VC29005

Function did not complete. Contact your service provider.