RPG/400 Help

READE (Read Equal Key)

*---------*---------------*-----------------*----------------*---------------*
|   CODE  |    FACTOR 1   |     FACTOR 2    |     RESULT     |  INDICATORS   |
|         |               |                 |      FIELD     |               |
*---------*---------------*-----------------*----------------*---------------*
| READE   | Search        | File name,      | Data           |   _ ER EOF    |
| (N)     | argument      | Record name     | structure      |               |
*---------*---------------*-----------------*----------------*---------------*

The READE operation retrieves the next sequential record from a full procedural file (identified by an F in position 16 of the file description specifications) if the key of the record matches the search argument. If the key of the record does not match the search argument, the indicator that must be specified in positions 58 and 59 is set on, and the record is not returned to the program.

Factor 1, the search argument, is optional and identifies the record to be retrieved. It can be a field name, a literal, a named constant, or a figurative constant. You can also specify a KLIST name in factor 1 for an externally described file. If factor 1 is left blank and the full key of the next record is equal to that of the current record, the next record in the file is retrieved. The full key is defined by the record format or file used in factor 2.

Note:
If factor 1 equals the key of the current record or if factor 1 is not specified, the key comparison takes place at the Data Management level; otherwise, it takes place within the RPG/400 program. If the file being read is defined as update and the compare is by RPG, a temporary lock on the next record is requested and the search argument is compared to the key of that record. If the record is already locked, the program must wait until the record is available before obtaining the temporary lock and making the comparison. If the comparison is unequal, the record-not-found indicator is turned on, and the temporary record lock is removed. If no lock (N in position 53) is specified, a temporary lock is not requested.

Factor 2 must contain the name of the file or record format to be retrieved. A record format name in factor 2 is allowed only with an externally described file (identified by an E in position 19 of the file description specifications).

The result field can contain the name of a data structure into which the record is read only if the file named in factor 2 is a program described file (identified by an F in position 19 of the file description specifications). See File Operations for a description of the way data is transferred between the file and data structure.

If the file you are reading is an update disk file, you can specify an N in position 53 to indicate that no lock should be placed on the record when it is read. See the RPG/400* User's Guide for more information.

You can specify a resulting indicator in positions 56 and 57 to be set on if the operation does is completed successfully. You must specify a resulting indicator in positions 58 and 59. The indicator is set on if a record is not found with a key equal to the search argument or if end of file occurs. If a READE operation is not successful, you must reposition the file (for example, by a CHAIN (Random Retrieval from a File), SETGT (Set Greater Than), or SETLL (Set Lower Limit) operation).

If factor 1 is specified and one or more key fields in the file being read from are defined with ALTSEQ, ABSVAL, DIGIT, or ZONE, the result of the read operation may differ from that expected. The reason is the content of the field on which the access path is built may not be the same as the content that the READE operation is using for its internal comparison.

A READE (with factor 1 specified) that immediately follows an OPEN operation or an EOF condition retrieves the first record in the file if the key of the record matches the search argument. A READE (with no factor 1 specified) that immediately follows an OPEN operation or an EOF condition results in an error condition. The error indicator, if specified, in positions 56 and 57 is set on. No further I/O operations can be issued against the file until it is successfully closed and reopened.

Note:
If the key used contains a numeric (packed or zoned) field, the search argument must exactly match the key field. For example, if the physical file uses a packed key of X'123C' for +123. and the search argument is 123, READE will use X'123F' and EOF will be returned.

Figure "READE Operation" shows READE operations with a file name and record format name specified in factor 2.

READE Examples

Figure 46. READE Operation

*...1....+....2....+....3....+....4....+....5....+....6....+....7...
CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++
C*
C*  With Factor 1 Specified...
C*
C*  The READE operation retrieves the next record from the file
C*  FILEA and compares its key to the search argument, KEYFLD.
C*  Indicator 55 is set on if KEYFLD is not equal to the key of
C*  the record read or if end of file is encountered.
C*
C           KEYFLD    READEFILEA                    55 NOT EQUAL
C*
C*  The READE operation retrieves the next record of the type REC1
C*  from an externally described file and compares the key of the
C*  record read to the search argument, KEYFLD.  (REC1 is a record
C*  format name.)  Indicator 56 is set on if KEYFLD is not equal to
C*  the key of the record read or if end of file is encountered.
C           KEYFLD    READEREC1                     56 NOT EQUAL
C*
C*  With No Factor 1 Specified...
C*
C*  The READE operation retrieves the next record in the access
C*  path from the file FILEA if the key value is equal to
C*  the key value of the record at the current cursor position.
C*  If the key values are not equal, indicator 55 is set on.
C                     READEFILEA                    55 NOT EQUAL
C*
C*  The READE operation retrieves the next record in the access
C*  path from the file FILEA if the key value equals the key value
C*  of the record at the current position.  REC1 is a record format
C*  name.  Indicator 56 is set on if the key values are unequal.
C*  N in position 53 indicates that the record is not locked.
C                     READEREC1                N    56 NOT EQUAL


[ Top of Page | Previous Page | Next Page | Table of Contents ]