Read Record using CLF (READRCDCLF)
The Read Record using CLF (READRCDCLF) command is used by a CL program to read data from a file. The command reads a record from the file and makes the data available to the CL application as one or more CL variables.
The CL variables must be declared in the CL program. Common ways to declare the CL variables are commands such as Declare File using CLF (DCLFCLF), Generate File Field Definition (GENFFDCLF), Declare Indicators using CLF (DCLINDCLF), Generate Indicators using CLF (GENINDCLF), a user provided Declare CL Variable (DCL) command, or a user provided Declare File (DCLF) command.
Restrictions:
- This command is valid only within a CL program.
- Not all TYPE values can be used on all files or records. For instance TYPE(*CHG) only applies to subfile records in a display file (*DSPF). See the TYPE parameter for more information.
- The file identified by the FILEID parameter must have been previously opened using the Open File using CLF (OPNFCLF) command with either USAGE(*INPUT) or USAGE(*BOTH).
- The combination of READRCDCLF, WRTREADCLF, and EXFMT commands in a single CL program canot exceed 499,999.
- Input/Output operations to a CLF shared file open should not be run concurrently among threads in a job. A shared file open is one where the OPNPGM parameter has been specifed with a value other than *CURPGM. If application thread serialization is used CLF shared files will utilize a common I/O feedback information area.
| Keyword | Description | Choices | Notes |
| FILEID |
File identifier |
Simple name |
Optional, Positional 1 |
| TYPE |
Type of read |
*NXT, *KEY, *RRN, *CHG, *PRV, *FIRST, *LAST, *INV, *SAME |
Optional, Positional 2 |
| RCDFMT |
Record format |
Character value, *ONLY |
Optional |
| EOF |
End of file |
Logical value |
Optional |
| RCDNOTFND |
Record not found |
Logical value |
Optional |
| ERR |
Error found |
Logical value |
Optional |
| RCDBUF |
Parameter to receive record |
Character value |
Optional |
| RCDLCK |
Record lock |
*OPNF, *NO |
Optional |
| RRN |
Relative record number |
Unsigned integer |
Optional |
| KEYREL |
Key relation |
*EQ, *NXTEQ, *LE, *GE, *GT, *LT, *PRVEQ, *NXTUNQ, *PRVUNQ |
Optional |
| KEYLIST |
Key field list |
Values (up to 10 repetitions): Not restricted |
Optional |
| KEYSTRUCT |
Key field structure |
Element list |
Optional |
| Element 1: Number of key fields |
Unsigned integer |
| Element 2: Structure |
Character value |
| KEYCOUNT |
Key field count |
Integer |
Optional |
| OPNPGM |
Program opening file |
Single values: *CURPGM
Other values: Qualified object name |
Optional |
| Qualifier 1: Program opening file |
Name |
| Qualifier 2: Library |
Name, *CURLIB |
File identifier (FILEID)
Specifies the file identifier that was used on a previous 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.
When using the precompiler, and 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.
This is a required parameter when not using the CLF precompiler.
- simple-name
- Specify a name that matches the FILEID parameter value of a previous OPNFCLF command.
Type of read (TYPE)
Specifies the type of read to be performed with the file identifed by the FILEID parameter.
- *NXT
- The next record in the file is read. If the file was opened with ACCMTH(*RRN) specified the read will be based on arrival sequence. If the file was opened with ACCMTH(*KEY) specified the read will be based on key sequence. When specified the RRN, KEYREL, KEYLIST, KEYSTRUCT, and KEYCOUNT keywords cannot be used.
If the EOF keyword is not specified an end-of-file condition (escape message VC2501C) will exist if no further records exist. If both the EOF and RCDNOTFND keywords are specified both program variables associated with these keywords will be set to on (true). The record-not-found escape message VC2501B will not be sent with this TYPE value.
This operation is valid for all file types except printer.
- *KEY
- The record to be read is identified by key value. Depending on the value specifed with the KEYREL keyword the key value actually used might be determined by:
- the current READRCDCLF command and the KEYLIST or KEYSTRUCT keyword values
- the key of the record the file is currently positioned to (KEYCOUNT)
For further information see the KEYREL keyword. When TYPE(KEY) is specified the KEYREL keyword must also be specified. The RRN keyword cannot be used.
TYPE(*KEY) is only valid for database and DDM files.
- *RRN
- The record to be read is identified by the RRN parameter. Regardless of the ACCMTH selected when opening the file, the record read will be based on the arrival sequence access path for the file identified by the FILEID keyword.
When specified the RRN keyword is required and the KEYREL, KEYLIST, and KEYSTRUCT keywords cannot be used.
This operation is only valid for database, DDM, and display subfiles.
- *CHG
- The record to be read is the next changed record within a subfile. When specified the RRN, KEYREL, KEYLIST, KEYSTRUCT, and KEYCOUNT keywords cannot be used.
Following a successful read the relative record number of the subfile record read can be retrieved using the Read Record using CLF RTVFINFCLF command and CURRRN. An end-of-file condition will exist when all changed subfile records have been read.
This operation is only valid for display subfile records.
- *PRV
- The previous record in the file is read. If the file was opened with ACCMTH(*RRN) specified the read will be based on arrival sequence. If the file was opened with ACCMTH(*KEY) specified the read will be based on key sequence. When specified the RRN, KEYREL, KEYLIST, KEYSTRUCT, and KEYCOUNT keywords cannot be used.
If the EOF keyword is not specified an end-of-file condition (escape message VC2501C) will exist if no further records exist. If both the EOF and RCDNOTFND keywords are specified both program variables associated with these keywords will be set to on. The record-not-found escape message VC2501B will not be sent with this TYPE value.
This operation is only valid for database and DDM files.
- *FIRST
- The first record in the file is read. If the file was opened with ACCMTH(*RRN) specified the read will be based on arrival sequence. If the file was opened with ACCMTH(*KEY) specified the read will be based on key sequence. When specified the RRN, KEYREL, KEYLIST, KEYSTRUCT, and KEYCOUNT keywords cannot be used.
If the EOF keyword is not specified an end-of-file condition (escape message VC2501C) will exist if there are no records in the file. If both the EOF and RCDNOTFND keywords are specified both program variables associated with these keywords will be set to on. The record-not-found escape message VC2501B will not be sent with this TYPE value.
This operation is only valid for database and DDM files.
- *LAST
- The last record in the file is read. If the file was opened with ACCMTH(*RRN) specified the read will be based on arrival sequence. If the file was opened with ACCMTH(*KEY) specified the read will be based on key sequence. When specified the RRN, KEYREL, KEYLIST, KEYSTRUCT, and KEYCOUNT keywords cannot be used.
If the EOF keyword is not specified an end-of-file condition (escape message VC2501C) will exist if there are no records in the file. If both the EOF and RCDNOTFND keywords are specified both program variables associated with these keywords will be set to on. The record-not-found escape message VC2501B will not be sent with this TYPE value.
This operation is only valid for database and DDM files.
- *INV
- Data from any invited device attached to the file, and that has data available, will be read. When specified the RRN, KEYREL, KEYLIST, KEYSTRUCT, and KEYCOUNT keywords cannot be used.
Following a successful read the device providing the data can be retrieved using the Retrieve File Info using CLF RTVFINFCLF command with keyword CURDEVD.
This operation is only valid for display and ICF files.
- *SAME
- The current (or same) record in the file is read. When specified the RRN, KEYREL, KEYLIST, KEYSTRUCT, and KEYCOUNT keywords cannot be used.
This operation is only valid for database and DDM files when record blocking is not being used.
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).
End of File can be returned when using TYPE or KEYREL operations that are relative to the current position in the file. Some of the operations that can return end-of-file include:
- Attempting to read past the last record in a file with TYPE(*NXT)
- Attempting to read a record prior to the first record in a file with TYPE(*PRV)
- Attempting to read a record using TYPE(*KEY) and KEYREL(*NXTEQ) when there are no additional records with the specified key value.
Record not found (RCDNOTFND)
Specifies a logical CL variable to receive Record Not Found status. If the variable value is equal to '1' (true) then the requested record was not found when performing the read command. If the variable value is equal to '0' (false) then the requested record was found.
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 &RNF.
If no CL variable is specified and a record not found condition is encountered the application program will be sent escape message VC2501B.
- 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).
Parameter to receive record (RCDBUF)
When using the CLF precompiler support (CRTBNDCLF, CRTCLFMOD, or CRTCLFPGM), and the specified FILEID is defined using the DCLFCLF command, this keyword should not be specified. The precompiler will determine the appropriate RCDBUF value to be used. If this keyword is used and the CL variable specified is not the same as what the precompiler would have calculated then the user is responsible for all processing of the CL variable when the READRCDCLF command completes.
If not using the CLF precompiler this keyword is required and identifies the CL variable to receive the record data being read. This CL variable is typically defined by the Generate File Field Definition (GENFFDCLF) command and has the same name as the record format name unless the file and record format names are the same.
- character-value
- Specify the name of a CL variable to receive the record buffer. This CL variable is typically declared by the Generate File Field Definition (GENFFDCLF) command.
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.
Relative record number (RRN)
Specifies the relative record number of the record to be read. This keyword is only valid when the TYPE parameter value is *RRN.
- unsigned integer
- Specify the relative record number of the record to be read.
Key relation (KEYREL)
Specifies how a key value is to be used when reading a record. The file must have been opened with ACCMTH(*KEY) and the current TYPE parameter must be *KEY.
- *EQ
- The first record in the file that has the specified key is to be read. A key value must be specified with either the KEYLIST or KEYSTRUCT keyword.
The End-of-File condition will not be set by this KEYREL value.
- *NXTEQ
- Relative to the current position in the file the next record in the file is returned if it has a key equal to the specified value. The key value to be used for testing equality can be specified in one of three ways. If a key value is provided using either the KEYLIST or KEYSTRUCT keyword then that value is used. If a KEYCOUNT is provided then the key values, for the number of key fields specified, from the record the file is currently positioned at are used.
As an example assume the following keyed file, VC2DPT, is in use:
Key Value Data
A1 Record 1
CO Record 2
MN Record 3
If the CLF application runs the command
POSDBFCLF FILEID(VC2DPT) TYPE(*KEY) +
KEYREL(*GE) KEYLIST(A2)
and there is no record with a key value of 'A2' then the command
READRCDCLF FILEID(VC2DPT) TYPE(*KEY) +
KEYREL(*NXTEQ) KEYCOUNT(1)
will return record number 2 as the key value of 'CO' satisfies the earlier positioning key relation of greater than or equal to 'A2'. Using the previous READRCDCLF command a second time would result in an end-of-file condition as the key value MN is not equal to the key value of the record currently positioned to (CO).
Changing the previous READRCDCLF command to
READRCDCLF FILEID(VC2DPT) TYPE(*KEY) +
KEYREL(*NXTEQ) KEYLIST(A2)
would cause an end-of-file condition to immediately exist on the READRCDCLF command as a key value of 'A2' is explicitly specified using the READRCDCLF KEYLIST keyword.
If the EOF keyword is not specified an end-of-file condition (escape message VC2501C) will exist if no further equal values exist. If both the EOF and RCDNOTFND keywords are specified both program variables associated with these keywords will be set to on. The record-not-found escape message VC2501B will not be sent with this KEYREL value.
- *LE
- The first record in the file that has a key less than or equal to the specified key is read. A key value must be specified with either the KEYLIST or KEYSTRUCT keyword.
As an example assume the following keyed file, VC2DPT, is in use:
Key Value Data
A1 Record 1
CO Record 2
MN Record 3
If the CLF application runs the command
READRCDCLF FILEID(VC2DPT) TYPE(*KEY) +
KEYREL(*LE) KEYLIST(DE)
then record number 2 will be returned as the key value 'CO' meets the requirements of being less than or equal to 'DE'.
The End-of-File condition will not be set by this KEYREL value.
- *GE
- The first record in the file that has a key greater than or equal to the specified key is read. A key value must be specified with either the KEYLIST or KEYSTRUCT keyword.
The End-of-File condition will not be set by this KEYREL value.
- *GT
- The first record in the file that has a key greater than the specified key is read. A key value must be specified with either the KEYLIST or KEYSTRUCT keyword.
As an example assume the following keyed file, VC2DPT, is in use:
Key Value Data
A1 Record 1
CO Record 2
MN Record 3
If the CLF application runs the command
READRCDCLF FILEID(VC2DPT) TYPE(*KEY) +
KEYREL(*GT) KEYLIST(DE)
then record number 3 will be returned as the key value 'MN' meets the requirements of being greater than 'DE'.
The End-of-File condition will not be set by this KEYREL value.
- *LT
- The first record in the file that has a key less than the specified key is read. A key value must be specified with either the KEYLIST or KEYSTRUCT keyword.
The End-of-File condition will not be set by this KEYREL value.
- *PRVEQ
- Relative to the current position in the file the previous record in the file is returned if it has a key equal to the specified value. The key value to be used for testing equality can be specified in one of three ways. If a key value is provided using either the KEYLIST or KEYSTRUCT keyword then that value is used. If a KEYCOUNT is provided then the key values, for the number of key fields specified, from the record the file is currently positioned at are used.
As an example assume the following keyed file, VC2EMPDPT, is in use where the key is defined as First name within Department.
Department First Name Data
A1 Amie Record 1
A1 Bruce Record 2
A1 Mindy Record 3
A1 Richard Record 4
A1 Wayne Record 5
CO Kiernan Record 6
If the CLF application runs the following two commands:
POSDBFCLF FILEID(VC2EMPDPT) TYPE(*KEY) +
KEYREL(*GT) KEYLIST(A1)
READRCDCLF FILEID(VC2EMPDPT) TYPE(*KEY) +
KEYREL(*PRVEQ) KEYCOUNT(1)
then an end-of-file condition will exist as the POSDBFCLF command is positioning the file to Record 6 (the key value of CO is greater than the keylist value of A1) and the READRCDCLF command is requesting the previous record in the file with a key value equal to CO (the current file position). The previous record in this case has a key value of A1.
If the CLF application runs the following four commands:
POSDBFCLF FILEID(VC2EMPDPT) TYPE(*KEY) +
KEYREL(*GT) KEYLIST(A1)
READRCDCLF FILEID(VC2EMPDPT) TYPE(*PRV)
READRCDCLF FILEID(VC2EMPDPT) TYPE(*KEY) +
KEYREL(*PRVEQ) KEYCOUNT(1)
SNDPGMMSG MSG(&EMPFNAME)
then the first name Richard will be shown. The POSDBFCLF command causes the file to be positioned to Record 6, the READRCDCLF TYPE(*PRV) causes Record 5 to be read, and the READRCDCLF KEYREL(*PRVEQ) causes Record 4 to be read as the first key field for Record 5 is A1 and the first key field for Record 4 is also equal to A1.
If you wanted to process the last record associated with the specific key value of A1 the following three commands could be used:
POSDBFCLF FILEID(VC2EMPDPT) TYPE(*KEY) +
KEYREL(*GT) KEYLIST(A1)
READRCDCLF FILEID(VC2EMPDPT) TYPE(*KEY) +
KEYREL(*PRVEQ) KEYLIST(A1)
SNDPGMMSG MSG(&EMPFNAME)
In this case the first name Wayne will be shown. The POSDBFCLF command causes the file to be positioned to Record 6, the READRCDCLF TYPE(*PRVEQ) with KEYLIST(A1) causes Record 5 to be read as the key for Record 5 is equal to A1.
If the EOF keyword is not specified an end-of-file condition (escape message VC2501C) will exist if no further equal values exist. If both the EOF and RCDNOTFND keywords are specified both program variables associated with these keywords will be set to on. The record-not-found escape message VC2501B will not be sent with this KEYREL value.
- *NXTUNQ
- The next record that has a key unique from the key value of the current record is to be read. The number of key fields to be used for testing can be specified using KEYLIST, KEYSTRUCT, or KEYCOUNT. With any of the three methods only the number of key fields identified is used. The key values associated with KEYLIST and KEYSTRUCT are ignored.
As an example assume the following keyed file, VC2EMPDPT, is in use where the key is defined as First name within Department.
Department First Name Data
A1 Amie Record 1
A1 Bruce Record 2
A1 Mindy Record 3
A1 Richard Record 4
A1 Wayne Record 5
CO Kiernan Record 6
If the CLF application runs the following three commands:
READRCDCLF FILEID(VC2EMPDPT) TYPE(*KEY) +
KEYREL(*EQ) KEYLIST(A1)
READRCDCLF FILEID(VC2EMPDPT) TYPE(*KEY) +
KEYREL(*NXTUNQ) KEYLIST(XX)
SNDPGMMSG MSG(&EMPFNAME)
then the first name Kiernan will be shown. The initial READRCDCLF causes Record 1 to be read as that is the first record with a key value equal to A1. The subsequent READRCDCLF KEYREL(*NXTUNQ) causes Record 6 to be read as Records 2, 3, 4, and 5 all have the same key value of A1. Record 6 is the first record encountered with a key value unique from the current records key value of A1. The value 'XX' for the KEYLIST keyword is not used. But as only one key field is used for the KEYLIST keyword only the first key field of the current record is used when determining the next unique key field value.
If the second READRCDCFL command is changed from KEYLIST(XX) to
READRCDCLF FILEID(VC2EMPDPT) TYPE(*KEY) +
KEYREL(*NXTUNQ) KEYLIST(XX XX)
the addition of the second parameter to the KEYLIST keyword will cause a test for uniqueness using both the department ID and the employee first name. With this change Record 2 will be read as the second key field value for Record 2 is 'Bruce', and this value is unique from the corresponding key field value for Record 1 ('Amie').
If the EOF keyword is not specified an end-of-file condition (escape message VC2501C) will exist if no further unique values exist. If both the EOF and RCDNOTFND keywords are specified both program variables associated with these keywords will be set to on. The record-not-found escape message VC2501B will not be sent with this KEYREL value.
- *PRVUNQ
- The previous record that has a key unique from the key value of the current record is to be read. The number of key fields to be used for testing can be specified using KEYLIST, KEYSTRUCT, or KEYCOUNT. With any of the three methods only the number of key fields identified is used. The key values associated with KEYLIST and KEYSTRUCT are ignored.
As an example assume the following keyed file, VC2EMPDPT, is in use where the key is defined as First name within Department.
Department First Name Data
A1 Amie Record 1
A1 Bruce Record 2
A1 Mindy Record 3
A1 Richard Record 4
A1 Wayne Record 5
CO Kiernan Record 6
If the CLF application runs the following three commands:
READRCDCLF FILEID(VC2EMPDPT) TYPE(*KEY) +
KEYREL(*EQ) KEYLIST(CO)
READRCDCLF FILEID(VC2EMPDPT) TYPE(*KEY) +
KEYREL(*PRVUNQ) KEYLIST(XX)
SNDPGMMSG MSG(&EMPFNAME)
then the first name Wayne will be shown. The initial READRCDCLF causes Record 6 to be read as that is the first record with a key value equal to CO. The subsequent READRCDCLF KEYREL(*PRVUNQ) causes Record 5 to be read as the key value is not CO. The value 'XX' for the KEYLIST keyword is not used. But as only one key field is used for the KEYLIST keyword only the first key field of the current record is used when determining the previous unique key field value.
If the EOF keyword is not specified an end-of-file condition (escape message VC2501C) will exist if no further unique values exist. If both the EOF and RCDNOTFND keywords are specified both program variables associated with these keywords will be set to on. The record-not-found escape message VC2501B will not be sent with this KEYREL value.
Key field list (KEYLIST)
Specifies the key values to be used when reading a record. This keyword can only be specified with TYPE(*KEY). When TYPE(*KEY) is specified, either this keyword, the KEYSTRUCT keyword, or the KEYCOUNT keyword can be specified depending on the value of the KEYREL keyword.
You can specify up to 10 values for this parameter. Each value specified corresponds to one key field in the file's key definition. The definition of the CL variable used does not have to match the definition of the key field within the file. The two definitions can be of different TYPE and LEN. In addition, character expressions can be used.
If the file has a composite key it is not necessary to provide all key values. Read by partial key is supported. If a file has three key fields, you can specify one, two, or all three key field values with this parameter.
When specifying numeric variables or numeric literals, any valid numeric datatype can be used. For instance the CL variable may be declared as TYPE(*DEC) while the file key field is defined as TYPE(*INT). When using numeric variables or literals the maximum number of digits at runtime that can be represented to the left of the decimal point is nine. At runtime the maximum number of digits to the right of the decimal point is five. When using a CL variable the variable can be declared with a larger size, for instance TYPE(*DEC) LEN(15 0), but at run time the actual value must be within the range of .00001 to 9999999999.99999.
If the numeric value is outside of this range the system will send message CPF0001 (Error found on READRCDCLF command) prior to running the command. For numeric keys that exceed this range you can pass the numeric value as a character value or use the KEYSTRUCT parameter. The following examples demonstrate how to use a character value for numeric keys with a value greater than 9999999999.99999.
The first example uses a character variable with a length of 30 to represent the numeric value. The second example uses a character literal to represent a numeric value of 15 digits.
/* Using a large character variable */
Dcl Var(&Char) Type(*Char) Len(30)
Dcl Var(&Dec) Type(*Dec) Len(15 0) +
Value(123456789012345)
ChgVar Var(&Char) Value(&DEC)
ReadRcdCLF FileID(BIGKEY) Type(*Key) KeyRel(*EQ) +
KeyList(&Char)
/* or using a character literal value */
ReadRcdCLF FileID(BIGKEY) Type(*Key) KeyRel(*EQ) +
KeyList('123456789012345')
You cannot specify KEYLIST, KEYSTRUCT, and KEYCOUNT keywords with the same command. Only one of these keywords can be used.
- unrestricted-value
- Specify the CL variables, or literal values, that contain the key values to be used. There must be one CL variable, or literal value, specified for each key field to be used.
When working with files with multiple keys you do not have to specify all key fields. Only specify those key values that you want used when reading a record. You cannot however omit key values. For example, if the file has five key fields defined and you want to specify key field 3 then you must also specify key fields 1 and 2. You do not however need to specify values for keys 4 and 5.
Key field structure (KEYSTRUCT)
Specifies the key values to be used when reading a record. This keyword can only be specified with TYPE(*KEY). When TYPE(*KEY) is specified either this keyword, the KEYLIST keyword, or the KEYCOUNT keyword can be specified depending on the value of the KEYREL keyword.
You cannot specify KEYSTRUCT, KEYLIST, and KEYCOUNT keywords with the same command. Only one of these keywords can be used.
Element 1: Number of key fields
- unsigned-integer
- Specify the number of key fields within the structure element that are to be used. If the file has a composite key it is not necessary to provide all key values. Read by partial key is supported.
Element 2: Structure
- character-value
- Specify the CL variable that contains the key values. The key fields provided in the CL variable must be declared with the same type and length as the key fields defined within the keyed access path being used.
A key field structure can be defined using either the Declare File Key Structure (DCLFKSCLF) or the Generate File Key Structure (GENFKSCLF) command.
Key field count (KEYCOUNT)
Specifies the number of key fields to be used from the record currently positioned to when using a KEYREL value of *NXTEQ, *PRVEQ, *NXTUNQ, or *PRVUNQ.
You cannot specify KEYSTRUCT, KEYLIST, and KEYCOUNT keywords with the same command. Only one of these keywords can be used.
- unsigned integer
- Specify the number of key fields from the current record to be tested for equality/uniqueness.
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 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 READRCDCLF
Example 1: Read the Initial Record of a File
ReadRcdCLF FileID(VC2EMP) Type(*First)
Example 2: Reading an Employee Record by Key
Pgm
/***********************************************/
/* Declare the Employee master file VC2EMP and */
/* CLF command related indicators */
/***********************************************/
DclFCLF FileID(VC2EMP)
DclIndCLF CLFInd(*Yes)
/***********************************************/
/* Open the file using keys */
/***********************************************/
OpnFCLF FileID(VC2EMP) AccMth(*Key)
/***********************************************/
/* Randomly read the employee record where */
/* the employee number is 205. */
/***********************************************/
ReadRcdCLF FileID(VC2EMP) Type(*Key) RcdNotFnd(&RNF) +
KeyRel(*EQ) KeyList(205)
/***********************************************/
/* Send the first name of the employee or a */
/* message if the record was not found */
/***********************************************/
If Cond(*Not &RNF) Then( +
SndPgmMsg Msg(&EmpFName))
Else Cmd(SndPgmMsg Msg('Record not found'))
/***********************************************/
/* Close the file and return */
/***********************************************/
CloFCLF FileID(VC2EMP)
EndPgm
The source for the example program can be found in member DEV_RDKEY of source file VC2CLSRC in library VC2CLF. The source for physical file VC2EMP can be found in member VC2EMP of source file QDDSSRC in library VC2CLF.
The VC2EMP database file should currently exist in library VC2CLF. To create DEV_RDKEY into QTEMP you can use the commands
AddLibLE Lib(VC2CLF)
CrtBndCLF Pgm(QTEMP/DEV_RDKEY) SrcFile(VC2CLSRC)
Example 3: Reading an Employee Record by RRN
/******************************************************/
/* This program randomly reads the 12th record of the */
/* VC2EMP physical file by relative record number. */
/* The employee name found (Ruth) is displayed. The */
/* record is then deleted and an attempt to read the */
/* same record made. The record should not be found */
/* as it has been deleted and a message is sent based */
/* on whether or not the record is successfully read. */
/* The program then writes a new 12th record to add */
/* a new employee. The program then re-reads the 12th */
/* record and displays the employee name found (Chad) */
/******************************************************/
Pgm
/******************************************************/
/* Declare the file and CLF indicators */
/******************************************************/
DclFCLF FileID(VC2EMP)
DclIndCLF CLFInd(*Yes)
/******************************************************/
/* Open the file for RRN access and update */
/******************************************************/
OpnFCLF FileID(VC2EMP) Usage(*Both)
/******************************************************/
/* Read the 12th record and display the name found */
/******************************************************/
ReadRcdCLF FileID(VC2EMP) Type(*RRN) RRN(12)
SndPgmMsg Msg(&EmpFName *BCat 'found')
/******************************************************/
/* Delete the record read and try to re-read it. */
/* A record-not-found condition should be returned. */
/******************************************************/
DltRcdCLF FileID(VC2EMP)
ReadRcdCLF FileID(VC2EMP) Type(*RRN) RRN(12) +
RcdNotFnd(&RNF)
If Cond(&RNF) Then( +
SndPgmMsg Msg('Record not found'))
Else Cmd(SndPgmMsg Msg( +
&EmpFName *BCat 'found after delete'))
/******************************************************/
/* Write a new record at the deleted position (RRN 12)*/
/******************************************************/
ChgVar Var(&EmpFName) Value('Chad')
ChgVar Var(&EmpSts) Value(F)
WrtRRNCLF FileID(VC2EMP) RRN(12)
/******************************************************/
/* Read the 12th record and display the name found */
/******************************************************/
ReadRcdCLF FileID(VC2EMP) Type(*RRN) RRN(12)
SndPgmMsg Msg(&EmpFName *BCat 'found after write')
/******************************************************/
/* Close the file and return */
/******************************************************/
CloFCLF FileID(VC2EMP)
EndPgm
The source for this example can be found in member DEV_RRNUSG of source file VC2CLSRC in library VC2CLF. The source for file VC2EMP can be found in member VC2EMP of source file QDDSSRC in library VC2CLF.
The VC2EMP file should currently exist in library VC2CLF. To compile DEV_RRNUSG into library QTEMP you can use the commands
AddLibLE Lib(VC2CLF)
CrtBNDCLF Pgm(QTEMP/DEV_RRNUSG) SrcFile(VC2CLSRC)
Prior to running DEV_RRNUSG you should reload the VC2EMP database file to ensure that the expected results are seen. To reload the file you can refer to the source member DEV_LOAD in source file VC2CLF/VC2CLSRC or Appendix D of the CLF Programmer's Guide.
After reloading the VC2EMP file you can call DEV_RRNUSG with the command
Call Pgm(QTEMP/DEV_RRNUSG)
You should see the following messages displayed
Ruth found
Record not found
Chad found after write
Example 4: Reading All Employees of a Department
/***********************************************/
/* The program requires one parameter - */
/* employee department (&EMPDPT). This */
/* variable name is the same as the field */
/* found in the file VC2EMPDPT, so there is */
/* no need to explicitly define it. It will */
/* be defined by the following DCLFCLF command */
/***********************************************/
Pgm Parm(&EmpDpt)
/***********************************************/
/* Declare the logical file VC2EMPDPT and CLF */
/* I/O related indicators. */
/* */
/* VC2EMPDPT is based on the Employee master */
/* file VC2EMP and has a composite key made */
/* of department ID (EMPDPT) and employee */
/* first name (EMPFNAME). */
/***********************************************/
DclFCLF FileID(DPT) File(VC2EMPDPT)
DclIndCLF CLFInd(*Yes)
/***********************************************/
/* Test if department parameter is passed */
/***********************************************/
ChgVar Var(&EmpDpt) Value(&EmpDpt)
MonMsg MsgID(MCH3601) Exec(Do)
RmvMsg Clear(*All)
SndPgmMsg Msg( +
'Department ID is a required parameter')
Return
EndDo
/***********************************************/
/* Open the VC2EMPDPT file using a FILEID of */
/* DPT. The file is opened for random access */
/* by key. */
/***********************************************/
OpnFCLF FileID(DPT) File(VC2CLF/VC2EMPDPT) +
AccMth(*Key)
/***********************************************/
/* Read the first record in the file with a */
/* key value equal to the department ID passed */
/* in as a parameter to the program. */
/* */
/* If no record is found for an employee in */
/* the department logical variable &RNF should */
/* be set to '1' (on). This variable is */
/* defined by the previous DCLINDCLF command. */
/***********************************************/
ReadRcdCLF FileID(DPT) Type(*Key) RcdNotFnd(&RNF) +
KeyRel(*EQ) KeyList(&EmpDpt)
/***********************************************/
/* If &RNF is "on": */
/* Send a message indicating that no */
/* department employees were found */
/* Close the VC2EMPDPT file */
/* Return */
/***********************************************/
If Cond(&RNF) Then(Do)
SndPgmMsg Msg('Department' *BCat &EmpDpt +
*BCat 'has no employees.')
CloFCLF FileID(DPT)
Return
EndDo
/***********************************************/
/* If employees were found: */
/* Send a message containing the employees */
/* first name */
/* Read the next employee record with the */
/* same department ID */
/* Continue reading and displaying until */
/* logical variable &EOF (End of File) */
/* is returned. This indicates that */
/* there are no more employees with the */
/* specified department ID */
/***********************************************/
DoWhile Cond(*Not &EOF)
SndPgmMsg Msg(&EmpFName)
ReadRcdCLF FileID(DPT) Type(*Key) +
EOF(&EOF) KeyRel(*NxtEQ) KeyList(&EmpDpt)
EndDo
/***********************************************/
/* When the last employee for the specified */
/* department has been displayed: */
/* Send a message indicating the department */
/* list is complete */
/* Close the file */
/* Return */
/***********************************************/
SndPgmMsg Msg('End of' *BCat &EmpDpt *BCat 'department +
listing')
CloFCLF FileID(DPT)
EndPgm
This example randomly reads the first employee record of the specified department and then reads all other employee records of the same department. The first name of each employee found is displayed to the user.
The source for this example can be found in member DEV_RDNXT of source file VC2CLSRC in library VC2CLF. The source for physical file VC2EMPDPT can be found in member VC2EMPDPT of source file QDDSSRC in library VC2CLF.
The VC2EMPDPT logical file should currently exist in library VC2CLF. To compile DEV_RDNXT into QTEMP you can use the commands
AddLibLE Lib(VC2CLF)
CrtBndCLF Pgm(QTEMP/DEV_RDNXT) SrcFile(VC2CLSRC)
To run the DEV_RDNXT program you can call it with the following commands
Call Pgm(QTEMP/DEV_RDNXT) Parm(A1) - to list A1 employees
Call Pgm(QTEMP/DEV_RDNXT) Parm(MS) - to list a department
with no employees
Example 5: Reading Changed Subfile Records
Pgm
/***********************************************/
/* Declare working variables */
/* &DPT_COUNT - used to load department records*/
/* to subfile */
/* &EMP_COUNT - used to load employee records */
/* to subfile */
/***********************************************/
Dcl Var(&Dpt_Count) Type(*Dec)
Dcl Var(&Emp_Count) Type(*Dec)
/***********************************************/
/* Declare files and indicators: */
/* VC2DPT - Department master file */
/* VC2EMP - Employee master file */
/* VC2EMPDPT - Logical file of employees by */
/* department */
/* VC2DPTDSP1 - Display file */
/* CLF command related indicators */
/***********************************************/
DclFCLF FileID(VC2DPT)
DclFCLF FileID(VC2EMP)
DclFCLF FileID(VC2EMPDPT)
DclFCLF FileID(DISPLAY) File(VC2DPTDSP1)
DclIndCLF CLFInd(*Yes)
/***********************************************/
/* Open the files. */
/***********************************************/
OpnFCLF FileID(DISPLAY) Usage(*Both)
OpnFCLF FileID(VC2DPT) AccMth(*Key)
OpnFCLF FileID(VC2EMP) AccMth(*Key)
OpnFCLF FileID(VC2EMPDPT) AccMth(*Key)
/***********************************************/
/* Initialize department subfile */
/***********************************************/
WrtRcdCLF RcdFmt(SFLCTLDPT)
/***********************************************/
/* Load list of departments into subfile */
/***********************************************/
ReadRcdCLF FileID(VC2DPT) Type(*First) EOF(&EOF)
DoWhile Cond(*Not &EOF)
/************************************/
/* Get department managers name */
/************************************/
ReadRcdCLF FileID(VC2EMP) +
Type(*Key) RcdNotFnd(&RNF) +
KeyRel(*EQ) KeyList(&DptMgr)
/************************************/
/* If no mgr, set to *NONE */
/************************************/
If Cond(*Not &RNF) Then(ChgVar +
Var(&DptMgrName) Value(&EmpFName))
Else Cmd(ChgVar +
Var(&DptMgrName) Value(*None))
/************************************/
/* Set depart. subfile record number*/
/* Write department record */
/* Get next department record */
/************************************/
ChgVar Var(&Dpt_Count) Value(&Dpt_Count + 1)
WrtRRNCLF RcdFmt(SFLDPT) RRN(&Dpt_Count)
ReadRcdCLF FileID(VC2DPT) Type(*Nxt) +
EOF(&EOF)
EndDo
/***********************************************/
/* If VC2DPT is empty then prompt to run the */
/* DEV_LOAD sample program */
/***********************************************/
If Cond(&Dpt_Count *EQ 0) Then(Do)
WrtReadCLF RcdFmt(EMPTYFILE)
ChgVar Var(&IN03) Value('1')
EndDo
/***********************************************/
/* Continue showing the department list until */
/* command key 3 is used */
/***********************************************/
DoWhile Cond(*Not &IN03)
/************************************/
/* Show active command keys and any */
/* messages that may have been sent */
/************************************/
WrtRcdCLF RcdFmt(KEY)
/************************************/
/* Clear message indicator */
/************************************/
ChgVar Var(&IN50) Value('0')
/************************************/
/* Show Subfile and Control record */
/************************************/
ChgVar Var(&IN21) Value('1')
WrtReadCLF RcdFmt(SFLCTLDPT)
/************************************/
/* Read subfile records to see if */
/* user wants to view the employees */
/* in the department (option 5) */
/************************************/
ReadRcdCLF RcdFmt(SFLDPT) TYPE(*CHG) +
EOF(&EOF)
DoWhile Cond(*Not &EOF)
If Cond(&SflOpt = '5') Then(Do)
/******************************/
/* First remove the '5' if */
/* one was typed in */
/******************************/
ChgVar Var(&SflOpt) Value(' ')
UpdRcdCLF RcdFmt(SFLDPT)
/******************************/
/* Now go display employees */
/******************************/
CallSubr Subr(Show_Emps)
EndDo
/*********************************/
/* That department is done. Now */
/* check if another was selected */
/*********************************/
ReadRcdCLF RcdFmt(SFLDPT) Type(*Chg) +
EOF(&EOF)
EndDo
EndDo
/***********************************************/
/* Close the files as command key 3 was used */
/***********************************************/
CloFCLF FileID(VC2EMP)
CloFCLF FileID(VC2DPT)
CloFCLF FileID(VC2EMPDPT)
CloFCLF FileID(DISPLAY)
/***********************************************/
/* And return to our caller */
/***********************************************/
Return
/***********************************************/
/* Subroutine to display department employees */
/***********************************************/
Subr Subr(Show_Emps)
/***********************************************/
/* Initialize employee subfile */
/***********************************************/
ChgVar Var(&IN21) Value('0') /* Clear SFL */
WrtRcdCLF RcdFmt(SFLCTLEMP)
/***********************************************/
/* Set employee subfile record number to 0 */
/* in case this isn't the first department */
/* the user selected today */
/***********************************************/
ChgVar Var(&Emp_Count) Value(0)
/***********************************************/
/* Load list of employees into subfile */
/***********************************************/
/***********************************************/
/* Position to first employee in department */
/***********************************************/
PosDBFCLF FileID(VC2EMPDPT) Type(*Key) +
RcdNotFnd(&RNF) KeyRel(*EQ) +
KeyList(&DptID)
/***********************************************/
/* If one was found, process all in department */
/***********************************************/
If Cond(*Not &RNF) Then(Do)
ReadRcdCLF FileID(VC2EMPDPT) Type(*Key) +
EOF(&EOF) KeyRel(*NxtEQ) KeyList(&DptID)
/************************************/
/* So long as there are employees */
/* in department: */
/************************************/
DoWhile Cond(*Not &EOF)
/************************************/
/* Set depart. subfile record number*/
/* Write department record */
/* Get next department record */
/************************************/
ChgVar Var(&Emp_Count) +
Value(&Emp_Count + 1)
WrtRRNCLF RcdFmt(SFLEMP) RRN(&Emp_Count)
ReadRcdCLF FileID(VC2EMPDPT) +
Type(*Key) EOF(&EOF) KeyRel(*NxtEQ) +
KeyList(&DptID)
EndDo
/************************************/
/* With all of the department */
/* employees loaded into the */
/* subfile, now display the active */
/* command keys */
/************************************/
WrtRcdCLF RcdFmt(KEY)
/************************************/
/* Show Subfile and Control record. */
/* When user hits ENTER or command */
/* key 3 return to main line. */
/************************************/
ChgVar Var(&IN21) Value('1')
WrtReadCLF RcdFmt(SFLCTLEMP)
EndDo
Else Cmd(Do)
/***********************************************/
/* No employees found in department */
/***********************************************/
ChgVar Var(&MsgTxt) +
Value('No employees in department' +
*BCat &DptID)
ChgVar Var(&IN50) Value('1')
EndDo
EndSubr
EndPgm
The source for this example can be found in member DEV_DPTU1 of source file VC2CLSRC in library VC2CLF. The source for file VC2DPT can be found in member VC2DPT of source file QDDSSRC in library VC2CLF. The source for file VC2EMP can be found in member VC2EMP of source file QDDSSRC in library VC2CLF. The source for file VC2EMPDPT can be found in member VC2EMPDPT of source file QDDSSRC in library VC2CLF. The source for file VC2DPTDSP1 can be found in member VC2DPTDSP1 of source file QDDSSRC in library VC2CLF.
All of the referenced objects should currently exist in library VC2CLF. To create this example program into QTEMP you can use the commands
AddLibLE Lib(VC2CLF)
CrtBndCLF Pgm(QTEMP/DEV_DPTU1) SrcFile(VC2CLSRC)
To run DEV_DPTU1 you can use the command
Call Pgm(QTEMP/DEV_DPTU1)
DEV_DPTU1 will display a subfile of the departments found in the VC2DPT department master file. From this subfile you can display the employees of one (or more) departments by using option 5. All departments contain employess other than Administrative Support. Command key 3 can be used to exit the program.
Error messages for READRCDCLF
*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.
|
