DCLF (Declare File)

DCLF Command syntax diagram

 

Purpose

The Declare File (DCLF) command declares one file (by name) to a control language (CL) program. Only one DCLF command is allowed in a CL program. The command specifies the name of the file and the record formats to be used in the program. After the file is declared, the program can contain the data manipulation commands (Send File (SNDF), Receive File (RCVF), Send/Receive File (SNDRCVF), End Receive (ENDRCV), and Wait (WAIT) for display device files, or RCVF for database files) that reference the file. This enables the program to interact with its user by sending data to and receiving data from a work station or database file. Database files can be used for input processing only.

When the CL program is compiled, a CL variable is automatically declared for each field in each record format used in the program. If the file is a nonfield level database file, the record format contains one field with the name of that record format. The field name becomes the variable name prefixed with an ampersand (&). The attributes of each declared field are the same as the attributes of the fields in the file. Fields defined in the record format as numeric are defined as decimal variables. Also, indicators used in the referenced file are declared as logical variables in the form &INnn, in which nn is the indicator number.

Variables automatically declared by the DCLF command can be used in the program the same as the variables declared by a DCL command. For example, indicators can be used in expressions and IF statements because they are declared as logical variables.

The content of the variables, not the variable names, are seen by the user; the display shows one, some, or all of the fields in the record format that can be filled in by the user. DDS determines the display format.

 

Restrictions

1. This command is valid only within CL programs. All declare commands (COPYRIGHT, Declare CL Variable (DCL) and Declare File (DCLF)) must follow the Program (PGM) command and precede any other command. The three types of declare commands can be placed in any order.
   
2. The file must either be a database file with only one record format or be a display file.
   
3. The file cannot be a mixed file, even if only display devices are defined for that mixed file.
   
4. The database file can be either physical or logical, and can be either field-level or nonfield level.
   
5. A file must exist before the program is created.

Because CL variables are automatically declared for each field in a referenced file's record formats, the following restrictions apply:

• If the file is changed (and the file description specifies that level checking is to be performed), the CL program must be recompiled to match the new file description. More information on level checking is in the Database Programming topic in the Information Center and the Application Display Programming book.
  
• If any field name is defined in more than one record format of the display file, the attributes in each record format for the commonly named field must match.
  
• Any CL variable declared in the program by a DCL command with the same name as an automatically declared CL variable (for a referenced field) must also have the same attributes specified in DDS for the referenced field.
  
• The variables used in the file must have data types supported for CL variables. However, fields defined as packed decimal format, zoned decimal format, or binary format are declared as decimal variables. The variables used in the file must have attributes that are valid for CL variables. For decimal variables, the limits are 15 digits and 9 decimal positions. For variables with more than 15 digits, CL will declare a character variable that is the number of digits, divided by 2, plus 1 (n / 2 + 1) in length. A CPI0306 message will be issued stating that the conversion has taken place, which can be seen in the program listing. For character variables, the limit is 9999 characters.

 

Required Parameters

FILE

Specifies the qualified name of the file used by the CL program. A CL variable name cannot be used to specify the file name.

The name of the file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

file-name: Specify the name of the file used by the CL program.

 

Optional Parameters

RCDFMT

Specifies the names of one or more file record formats used by the SNDF, RCVF, and SNDRCVF commands in the CL program. Database files can be processed only by RCVF. CL variable names cannot be specified in RCDFMT; only names of record formats can be used. For every field and indicator in each record format specified in RCDFMT, one CL variable is automatically declared in the program.

*ALL: Every record format in the file, up to 99, has its fields declared in the CL program as variables. If there are more than 99 record formats in the file, only the first 99 are used.

record-format-name: Specify one or more record format names whose fields are being declared as variables in the CL program. No more than 50 record format names can be specified; CL variables cannot be used to specify the names.

ALWVARLEN

Specifies whether variable length fields are allowed in record formats.

*NO: Record formats cannot contain variable length fields. A message is sent at compile time if variable-length fields are supported in the file.

*YES: Record formats can contain variable length fields. CL variables declared for variable-length fields are handled as type *CHAR with length equal to 2 bytes plus the maximum field length. Following a RCVF on a variable-length field, the first 2 bytes in the CL variable contain the length of the data. The data received from the field is padded on the right with blanks to the maximum length allowed (9997 bytes).

ALWNULL

Specifies whether a field value of null is allowed.

*NO: Values of null are not allowed. For each field containing a null value at RCVF time, a diagnostic message is sent with a single escape message for the entire record. Default values are placed in the CL program variables.

*YES: Values of null are allowed.

ALWGRAPHIC

Specifies whether graphic data fields are allowed in record formats.

*NO: Record formats cannot contain graphic data fields. A diagnostic message is sent at compile time if graphic data fields are supported in the file.

*YES: Record formats can contain graphic data fields. CL variables declared for graphic data fields are handled as type *CHAR with length equal (in bytes) to the graphic data field length.

Examples for DCLF

Example 1: Declaring Fields of All Record Formats as Variables

DCLF   FILE(ABLE)

This command specifies that the file named ABLE is used by the CL program to pass data between the user and the program. Because no library was specified, the library list is used to locate the file. RCDFMT was not specified; therefore, all the fields and indicators in all the record formats are automatically declared as variables, and data from any field in any record format (up through the first 99) in the file can be passed between the program and the user. No device file routing data is received by the program.

Example 2: Using Multiple Record Formats

DCLF   FILE(BAKER)  RCDFMT(REC2 REC6)

Display file BAKER is used by the CL program to pass data between the user and the program. Because no library was specified, the library list is used to locate the file. Both the REC2 and REC6 record formats are used. Device file routing data is returned to the program and stored in the CL variable &FB for each RCVF and SNDRCVF command.

Additional Considerations

File processing is handled differently in CL programs, depending on whether the file specified in the DCLF command is a display file or a database file.

The following statements apply if the file is a display device file at compile time:

• The file must be a display device file at run time.
  
• The program may contain any or all of the following commands: SNDF, RCVF, SNDRCVF, ENDRCV, and WAIT.
  
• The file is opened for input and output.

The following statements apply if the file is a database file at compile time:

• The file must be a database file with a single record format at run time.
  
• The program may contain only RCVF commands; SNDF, SNDRCVF, ENDRCV, and WAIT commands are not allowed.
  
• The file is opened for input only.
  
• The file is opened by the RCVF command, not the OPNDBF command.

Error messages for DCLF

None