CL Command Reference - DCLF
CL Command List > DCLF Reference
Description:
The Declare File (DCLF) command declares one file (by name) to a Control Language (CL) program. Up to five DCLF commands are allowed in a CL procedure. Each DCLF command specifies the name of a display file or database file, the file record formats to be used in the program, and an optional open file identifier which is used to uniquely identify the declared instance of the file within the CL procedure. Multiple DCLF commands can reference the same file, so long as the value specified for the Open file identifier (OPNID) parameter is unique. Following the DCLF command for a file, the CL procedure can contain data manipulation commands. For display files, the following commands can be used to send data to a workstation and receive data from a workstation: Send File (SNDF), Receive File (RCVF), Send/Receive File (SNDRCVF), End Receive (ENDRCV), and Wait (WAIT). For database files, the RCVF command can be used to read records from the file.
When the CL procedure is compiled, a CL variable is automatically declared for each field in each record format used in the program. If the file is a record-level database file, the record format contains one field with the name of that record format. If the value specified for the OPNID parameter is *NONE, the variable name is the field name prefixed with an ampersand (&). If the OPNID parameter value is not *NONE, the variable name is the field name prefixed with an ampersand (&), the value specified for the OPNID parameter, and an underscore.
For example, if a declared file has a record format with field CUSTNAME and the open file identifier specified on the DCLF command was FILE1, the declared variable would be:
&FILE1_CUSTNAME
The attributes of each declared field are the same as the attributes of the field in the file record format. Fields defined in the record format as numeric are defined as decimal variables. Indicators defined in the referenced file record format are declared as logical variables with a variable name in the form INnn, where ĄŻ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:
. This command is valid only within CL procedures. All declare commands (DCL, COPYRIGHT, DCLF, and DCLPRCOPT) must follow the PGM (Program) command and must precede all other commands in the program. The four types of declare commands can be intermixed in any order.
. The file must either be a database file with only one record format or be a display file.
. The file cannot be a mixed file, even if only display devices are defined for that mixed file.
. The database file can be either physical or logical, and can be either field-level or nonfield level.
. The referenced file must exist before the program is created.
Examples:
Example 1: Declaring Fields of All Record Formats as Variables
DCLF FILE(ABLE) RCDFMT(*ALL)
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. 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.
Example 2: Using Multiple Record Formats
DCLF FILE(BAKER) RCDFMT(REC2 REC6)
Display file BAKER is used by the CL procedure to pass data between the user and the program. Assuming the library qualifier for FILE defaults to *LIBL, the library list is used to locate the file. Both the REC2 and REC6 record formats are used.
Example 3: Using an Open File Identifier
DCLF FILE(MYLIB/CHARLES) OPNID(CTLFILE1)
File CHARLES in library MYLIB is used by the the CL procedure to read records from the database file. If the record format contains a field named CUSTNUMBER, the following variable will be declared: &CTLFILE1_CUSTNUMBER