Receive File (RCVF)

The Receive File (RCVF) command is used by a CL program or ILE CL procedure 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.

Only one record format, of those specified in the DCLF command, can be specified in each RCVF command. If the file has not been opened by a previous RCVF, SNDRCVF, or SNDF command, it is opened by this command. If the file has been previously closed due to an end-of-file condition on a previous RCVF command, an error occurs. The file specified in this command can be overridden if the override command is entered before the file is opened. If the file specified in the DCLF command was a display file when the program was compiled, the file may only be overridden to another display file. If the file was a database file, the file may only be overridden to another database file that has a single record format. However, care should be taken that the fields in the overriding record format correspond to the CL variables declared in the program.

Restrictions:

Parameters

Keyword Description Choices Notes
DEV Display device Name, *FILE Optional, Positional 1
RCDFMT Record format Name, *FILE Optional, Positional 2
OPNID Open file identifier Simple name, *NONE Optional
WAIT Wait *YES, *NO Optional

Display device (DEV)

Specifies the name of the display device from which data is to be received. If a CL variable name is used in this parameter, only one RCVF command is needed in the program to receive data from several devices. (The variable specifying the device name can be changed while repeatedly running the same command.) This parameter may be specified only if the file is a display device file.

*FILE
The user's data is to be received from the device associated with the device file (the device file that was declared in the FILE parameter of the DCLF command). If more than one device name is specified in the device file, *FILE cannot be specified.
name
Specify the name of the device or the name of the CL variable that contains the name of the device from which the user's data is to be received.

Record format (RCDFMT)

Specifies the name of the record format that is used to receive data from the file. The format contains all the fields in the record. This parameter must be coded with a record format name if there is more than one record format in the device file. If the file is a database file, the specified record format is used to map the data from the record into the CL variables. The actual record format name in the file at run time may be different. RCVF ignores the INVITE DDS keyword.

*FILE
There is only one record format in the device file; that is the format in which the data is to be received. If more than one record format is specified in the device file, *FILE cannot be specified.
name
Specify the name of the record format in which the data records from the display device are to be received. A CL variable cannot be used to specify the record format name.

Open file identifier (OPNID)

Specifies the open file identifier that was declared on a preceding Declare File (DCLF) command in the same CL program or ILE CL procedure. A CL variable cannot be specified for this parameter value.

*NONE
No open file identifier is provided. This command will use the file associated with the DCLF command that had *NONE specified for the OPNID parameter. Only one file can be declared in a CL program or ILE CL procedure with *NONE as the open file identifier.
simple-name
Specify a name that matches the OPNID parameter value on a preceding DCLF command in the same CL program or ILE CL procedure.

Wait (WAIT)

Specifies whether the CL program or ILE CL procedure waits for the data to be received from the user's device or continues processing the commands that follow this RCVF command. If WAIT(*NO) is specified, the program must issue a WAIT command later in the program to complete the input operation. This parameter may be specified only if the file is a display device file.

*YES
The program waits until the input operation from the device is completed; the next command is not processed until then.
*NO
The program does not wait for the input data; commands continue running until a WAIT command is reached later in the program.

Examples

Example 1: Receive Data from Database File 

DCLF   FILE(MENU1)
 :
RCVF   OPNID(*NONE)

The CL program or ILE CL procedure receives data from the database file named MENU1. The RCVF command is associated with the Declare File command that does not have an open file identifier specified.

Example 2: Receive Data from Display Device 

DCLF   FILE(SCREENX)  RCDFMT(R1 R2)
 :
RCVF   DEV(DISPLAY2)  RCDFMT(R1)

The CL program or ILE CL procedure receives data from the user at the display station named DISPLAY2. The data is received in the record format named R1 in the device file named SCREENX. The procedure waits for the user data before it continues processing.

Example 3: Handling End-of-File Exception 

DCLF   FILE(INPUT)   OPNID(INFILE1)
 :
RCVF   OPNID(INFILE1)
MONMSG   CPF0864  EXEC(GOTO EOF)

The CL program or ILE CL procedure receives a record sequentially from the database file named INPUT. The procedure monitors for the end-of-file exception CPF0864 and goes to label EOF when the message is received.

Example 4: Using RCVF with WAIT command 

DCLF   FILE(MSCREEN)  RCDFMT(MIN1 MIN2 MIN3)
 :
RCVF   DEV(&DNAME)  RCDFMT(MIN2)  WAIT(*NO)
WAIT   DEV(&DNAME)

The CL program or ILE CL procedure receives user data from several devices one at a time by way of the device file named MSCREEN. The procedure receives data from the device named in the variable &DNAME using the record format MIN2, but it does not wait for the data to come in. The same RCVF command is used to receive data from several devices; because the CL variable &DNAME is used, only the device name in the DEV parameter must be changed each time the command is run. A WAIT command for each device must be issued later in the procedure because the WAIT command actually receives the data. Both the RCVF and the WAIT commands may be processed for each device (one at a time) to send data to the procedure. If a user response is delayed, the commands can be processed as many times as necessary until the user responds with the data or a End Receive (ENDRCV) command cancels the request.

Error messages

*ESCAPE Messages

CPF0859
File override caused I/O buffer size to be exceeded.
CPF0860
File &1 in &2 not a data base file.
CPF0861
File &1 in library &2 is not a display file.
CPF0863
Value of binary data too large for decimal CL variable.
CPF0864
End of file detected for file &1 in &2.
CPF0865
File &1 has more than one record format.
CPF0883
*FILE not valid in DEV parameter for file &1.
CPF0886
Record contains a data field that is not valid.
CPF4101
File &2 in library &3 not found or inline data file missing.
CPF502A
Variable length record error on member &4.
CPF502B
Error occurred in trigger program.
CPF502D
Referential constraint violation on member &4.
CPF502E
Referential constraints could not be validated for member &4.
CPF502F
Check constraint violation on member &4.
CPF5029
Data mapping error on member &4.
CPF503A
Referential constraint violation on member &4.
CPF503B
Record could not be inserted or updated in member &4.
CPF5068
Program device &4 not found in file &2 in library &3.
CPF5070
File &2 in library &3 has no program devices acquired.