WORKING WITH DATABASE FILES IN CL PROCEDURES

DCLF (Declare File) Command Description

DCLF FILE(library-name/file-name) RCDFMT(record-format-names)

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 command 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 non-field 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.

FROM THE DESK OF N.K. ELURU

Page 1

WORKING WITH DATABASE FILES IN CL PROCEDURES

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

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

FROM THE DESK OF N.K. ELURU

Page 2

WORKING WITH DATABASE FILES IN CL PROCEDURES

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.
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.
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 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.

Receiving Data from a Database File

FROM THE DESK OF N.K. ELURU
Page 3

WORKING WITH DATABASE FILES IN CL PROCEDURES

The only command you can use to receive data from a database file is the RCVF command.
When you run a RCVF command, the next record on the file's access path is read, and the values
of the fields defined in the database record format are placed in the corresponding CL variables.
Note that CL does not support zoned decimal or binary numbers. Consequently, fields in the
database file defined as zoned decimal or binary cause *DEC fields to be defined in the CL
procedure or program. *DEC fields are internally supported as packed decimal, and the RCVF
command performs the conversion from zoned decimal and binary to packed decimal as
required. Database files which contain floating point data cannot be used in a CL procedure or
program.
When the end of file is reached, message CPF0864 is sent to the procedure or OPM program.
The CL variables declared for the record format are not changed by the processing of the RCVF
command when this message is sent. You should monitor for this message and perform the
appropriate action for end of file. If you attempt to run additional RCVF commands after end of
file has been reached, message CPF0864 is sent again.

RCVF (Receive File) Command Description

Purpose
The Receive File (RCVF) command is used within a CL program to receive data from a display
device or database file. The command reads a record from the file and puts the data from the
record into one or more CL variables. These CL variables were automatically declared in the
program when the CL source program was compiled and a Declare File (DCLF) command was
processed as part of the source. There is one CL variable for each field in the record format used
to receive the data. The data that is entered by a user at the display or is contained in the input
record is copied into CL variables in the program by the RCVF command, where it is processed
by the program.
Examples for RCVF
Example 1
FROM THE DESK OF N.K. ELURU
Page 4

WORKING WITH DATABASE FILES IN CL PROCEDURES

DCLF FILE(MENU1)
*
*
*
RCVF
The CL program receives data from the user through the file named MENU1. The program waits
for the user data before it continues processing.
Example 3
DCLF FILE(INPUT)
*
RCVF
MONMSG CPF0864 EXEC(GOTO EOF)
The CL program receives a record sequentially from the database file named INPUT. The
program monitors for the end-of-file exception CPF0864 and goes to label EOF when the
message is received.

CL program to read a database file and display its fields value on

the console & prompt every time before reading a new record from
the file

FROM THE DESK OF N.K. ELURU

Page 5

WORKING WITH DATABASE FILES IN CL PROCEDURES

FROM THE DESK OF N.K. ELURU

Page 6

WORKING WITH DATABASE FILES IN CL PROCEDURES

FROM THE DESK OF N.K. ELURU

Page 7