Work with files in CL procedures

Two types of files are supported in CL procedures and programs: display files and database files.

You can send a display to a workstation and receive input from the workstation for use in the procedure or program, or you can read data from a database file for use in the procedure or program.

Note: Database files are made available for use within the CL procedure or program through the DCLF and Receive File (RCVF) commands.

To use a file in a CL procedure or program, you must:

Format the display or database record, identifying fields and conditions which you enter as DDS source. The use of DDS is not required for a database file.
Create the file using the Create Display File (CRTDSPF) command, Create Physical File (CRTPF) command, or Create Logical File (CRTLF) command. Subfiles (except for message subfiles) are not supported by CL procedures and programs.
For database files, add a member to the file using the Add Physical File Member (ADDPFM) command or
```
Add Logical File Member (ADDLFM)
```
command. This is not required if a member was added by the CRTPF or CRTLF commands. The file must have a member when the procedure or program is processed, but does not need to have a member when the procedure or program is created.
Refer to the file in the CL procedure using the DCLF command, and refer to the record format on the appropriate data manipulation CL commands in your CL source.
Create the CL module.
Create the program or service program.

Up to five display or database files can be referred to in a CL procedure. The support for database files and display files is similar as the same commands are used. However, there are a few differences, which are described here.

The following statements apply only to database files used with CL procedures and programs:
- Only database files with a single record format may be used by a CL procedure or program.
- The files may be either physical or logical files, and a logical file may be defined over multiple physical file members.
- Only input operations, with the RCVF command, are allowed. The WAIT and DEV parameters on the Receive File (RCVF) command are not allowed for database files. In addition, the SNDF, SNDRCVF, and ENDRCV commands are not allowed for database files.
- DDS is not required to create a physical file which is referred to in a CL procedure or program. If DDS is not used to create a physical file, the file has a record format with the same name as the file, and there is one field in the record format with the same name as the file, and with the same length as the record length of the file (RCDLEN parameter of the CRTPF command).
- The file need not have a member when it is created for the module or program. It must, however, have a member when the file is processed by the program.
- The file is opened for input only when the first Receive File (RCVF) command is processed. The file must exist and have a member at that time.
- The file remains open until the procedure or OPM program returns or when the end of file is reached. When end of file is reached, message CPF0864 is sent to the CL procedure or program, and additional operations are not allowed for the file. The procedure or program should monitor for this message and take appropriate action when end of file is reached.
The following statements apply only to display files used with CL procedures and programs:
- Display files may have up to 99 record formats.
- All data manipulation commands (SNDF, SNDRCVF, RCVF, ENDRCV and WAIT) are allowed for display files.
- The display file must be defined with the DDS.
- The display file is opened for both input and output when the first SNDF, SNDRCVF, or RCVF command is processed. The file remains open until the procedure or OPM program returns.

Note: The open does not occur for both types of files until the first send or receive occurs. Because of this, the file to be used can be created during the procedure or program and an override can be performed before the first send or receive. However, the file must exist before the module or program is compiled.

The format for the display is identified as a record format in DDS. Each record format may contain fields (input, output, and input/output), conditions/indicators, and constants. Several record formats can be entered in one display file. The display file name, record format name, and field names should be unique, because other HLLs may require it, even though CL procedures and programs do not.

Data manipulation commands
A CL procedure or program can use several commands, called data manipulation commands.
Refer to files in a CL procedure
Files are accessed during compiling of Declare File (DCLF) commands when CL modules and programs are created so that variables can be declared for each field in the file.
Open and close files in a CL procedure
When you use CL support, the file referred to is implicitly opened when you do your first send, receive, or send/receive operation. An opened display file remains open until the procedure or OPM program in which it was opened returns or transfers control. An opened database file is closed when end of file is reached, or when the procedure or OPM program in which it was opened returns or transfers control. Once a database file has been closed, it cannot be opened again during the same call of the procedure or OPM program.
Declare a file
The Declare File (DCLF) command is used to declare a display or database file to your CL procedure or program. The DCLF command cannot be used to declare files such as tape, printer, and mixed files.
Send and receive data with a display file
The only commands you can use with a display file to send or receive data in CL procedures and programs are the Send File (SNDF), Receive File (RCVF), and Send/Receive File (SNDRCVF) commands.
Write a CL program to control a menu
This example shows how a CL procedure can be written to display and control a menu.
Override display files in a CL procedure
You can use the Override with Display File (OVRDSPF) command to replace the display file named in a CL procedure or program or to change certain parameters of the existing display file. This may be especially useful for files that have been renamed or moved since the module or program was compiled.
Work with multiple device display files
The normal mode of operation on a system is for the workstation user to sign on and become the requester for an interactive job. Many users can do this at the same time, because each will use a logical copy of the procedure, including the display file in the procedure. Each requester calls a separate job in this kind of use. This is not considered to be multiple device display use.
Receive data from a database file
The only command you can use to receive data from a database file is the Receive File (RCVF) command.
Override database files in a CL procedure or program
You can use the Override with Database File (OVRDBF) command to replace the database file named in a CL procedure or program or to change certain parameters of the existing database file. This may be especially useful for files that have been renamed or moved since the procedure or program was created. It can also be used to access a file member other than the first member.
Refer to output files from display commands
A number of the IBM^® display commands allow you to place the output from the command into a database file (OUTFILE parameter). The data in this file can be received directly into a CL procedure or program and processed.

Parent topic: Objects and libraries

Related concepts

Parts of a CL procedure

Related tasks

Access files

Related information

CL command finder

Application Display Programming