The Read a Record (READ) command reads the next record from a file.

This command never runs in the traditional sense and will return an error if an attempt is made to run the command. The CLF precompilers, when they encounter this command in a CL source program, replace the command and generate CL instructions directly into the compiled CL program.

Restrictions:

• This command can only be used in a CL program that is created using a CLF precompiler command. The CLF precompiler commands are CRTBNDCLF, CRTCLFMOD, and CRTCLFPGM.
• The file identified by the FILEID parameter must be open with either USAGE(*INPUT) or USAGE(*BOTH).

Parameters

File identifier (FILEID)

Specifies the file identifier that was used on a previous Open File for Processing (OPEN) or Open File using CLF (OPNFCLF) command in the application.

This parameter is used by CLF commands to identify the file to be processed by the command.

If the file is declared using the DCLFCLF command this parameter is optional if the RCDFMT parameter specifies a record format name that is associated with one and only one file ID.

simple-name

Specify a name that matches the FILEID parameter value of a previous OPEN or OPNFCLF command.

Record format (RCDFMT)

Specifies the name of the record format to be used.

*ONLY

There is only one record format defined for the file. This record format will be used by the command.

character-value

Specify the name of the record format to be used.

End of file (EOF)

Specifies a logical CL variable to receive the end-of-file status. If the variable value is equal to '1' (true) then end-of-file was reached when performing the read command. If the variable value is equal to '0' (false) then end-of-file was not reached.

This CL variable is typically declared by either the Declare Indicators using CLF (DCLINDCLF) command or the Generate Indicators using CLF (GENINDCLF) command. These commands would have specified CLFIND(*YES). When using these commands the name of the declared CL variable is &EOF.

If no CL variable is specified and an end of file condition is encountered the application program will be sent escape message VC2501C.

logical-value

Specify the name of a CL variable declared as TYPE(*LGL).

Error found (ERR)

Specifies a CL logical variable to receive general error status. If the variable value is equal to '1' (true) then an error was found when performing the command. If the variable value is equal to '0' (false) then no error was found when performing the command.

This CL variable can be declared by the Declare Indicators using CLF (DCLINDCLF) command, the Generate Indicators using CLF (GENINDCLF) command, or by you using the Declare CL Variable (DCL) command. The two CLF commands would have specified CLFIND(*YES). When using the CLF commands the name of the CL variable is &ERR.

If no CL variable is specified and an error condition is encountered the application program will be sent an escape message.

logical-value

Specify the name of a CL variable declared as TYPE(*LGL).

Record lock (RCDLCK)

Specifies if the record being read should be locked.

*OPNF

The record being read will be locked based on the value specifed for the USAGE parameter when the file was opened. If the file is open with USAGE(*BOTH) then the record will be locked. Otherwise the record will not be locked.

*NO

The record will not be locked. If the job currently holds a lock on a record within the file the pre-existing lock will continue to be held. To release the lock you can use the Release Record using CLF (RLSRCDCLF) command.

Program opening file (OPNPGM)

The same FILEID value can be in use across multiple programs within a job. Each instance of a file open is uniquely identifed by the OPNPGM parameter. This parameter specifes the application program that initially opened the file using the Declare File using CLF (OPEN) or the Open File using CLF (OPNFCLF) command.

All CLF commands that reference the same FILEID and OPNPGM combination share the same view of the file. If one program causes the position within the file to change all programs see that change. If one program closes the file then the file is closed to all programs.

The combination of FILEID and OPNPGM must be unique within the activation group the application program is running in.

If the program name is *CURPGM then the library qualifier for this parameter is ignored. The library of the current program will be used.

Single values: Program opening file

*CURPGM

The current program opened the file associated with FILEID. It is this file open instance that is to be used.

Qualifier 1: Program opening file

name

Specify the name of the program that initially opened the file identified by FILEID. It is this file open instance that is to be used.

Qualifier 2: Library

*CURLIB

The current library for the thread is used. If there is no current library for the thread then library QGPL is used.

name

Specify the name of the library where the program that initially opened the file is located.

Examples for READ

Example 1: Sequentially Reading All Records in a File

    /******************************************************/
    /* This program has one (required) parameter, the     */
    /* name of a member within the QCLSRC source file     */
    /*                                                    */
    /* The program will list the contents of the          */
    /* specified source member.  Call this example from   */
    /* the command line in order to see the listing.      */
    /******************************************************/
    Pgm        Parm(&Member)
    Dcl        Var(&Member) Type(*Char) Len(10)
    /******************************************************/
    /* Declare our variables:                             */
    /*  The DCLFCLF will provide the external definition  */
    /*      for QCLSRC                                    */
    /*  The DCLINDCLF will provide the indicator to       */
    /*      detect End of File (&EOF)                     */
    /******************************************************/
    File       FileID(QCLSRC)
    Inds       CLFInd(*Yes)
    /******************************************************/
    /* Test to see if the &MEMBER parameter was passed    */
    /* (only needed for ILE programs). If not, end with   */
    /* an error message.                                  */
    /******************************************************/
    ChgVar     Var(&Member) Value(&Member)
    MonMsg     MsgID(MCH3601) Exec(Do)
               RmvMsg Clear(*All)
               SndPgmMsg  Msg( +
                 'Member name is a required parameter')
               Return
               EndDo
    /******************************************************/
    /* Open the file, this time with (by default) LVLCHK  */
    /*                                                    */
    /* Read the first record of the specified member      */
    /*                                                    */
    /* Enter a DoWhile loop conditioned by End of File    */
    /*   (&EOF). So long as EOF is not detected:          */
    /*   1. Send the line of source read to the default   */
    /*      (*PRV) call message queue                     */
    /*   2. Read the next QCLSRC record and loop          */
    /******************************************************/
    Open       FileID(QCLSRC) Mbr(&Member)
    Read       FileID(QCLSRC) EOF(&EOF)
    DoWhile    Cond(*Not &EOF)
               SndPgmMsg Msg(&SrcDta)
               Read QCLSRC EOF(&EOF)
               EndDo
    /******************************************************/
    /* When End of File close the file and return         */
    /******************************************************/
    Close      QCLSRC
    EndPgm

The source for this example can be found in member RPG_OPNF of source file VC2CLSRC in library VC2CLF.

To compile RPG_OPNF into QTEMP you can use the command

    CrtBndCLF Pgm(QTEMP/RPG_OPNF) SrcFile(VC2CLF/VC2CLSRC)

To run the program you can use any of the following commands

    Call Pgm(RPG_OPNF) Parm(RPG_OPNF) - list member RPG_OPNF
    Call Pgm(RPG_OPNF) Parm(*First)   - list the first member
    Call Pgm(RPG_OPNF) Parm(*All)     - list all members

Error messages for READ

*ESCAPE Messages

CPF0001

Error found on &1 command.

VC2501A

File &1 is not open for access by relative record number.

VC2501B

Record not found in file &1.

VC2501C

End of file for file &1.

VC25021

The &4 command was not successful when accessing File ID &2.

VC25025

Target datatype of &1 not recognized.

VC2502E

File ID &1 is not open.

VC25065

RCDBUF parameter is missing on &2 command.

VC25076

Record in file &1 is locked by another job.

VC29002

Function did not complete. See previously listed messages related to possible user errors.

VC29003

Function did not complete. See previously listed messages for possible cause.

VC29004

Function did not complete. See previously listed messages for possible cause.

VC29005

Function did not complete. Contact your service provider.

VC29013

Function did not complete. See previously listed messages for possible cause.