READNEXT

The READNEXT statement reads the next record in a specified file.

    ••••• READNEXT ••• •••••••••••••••••••••• HOLD • FT • BY ••••••••••••••••••••••
    (1)            (2) (3)                        (4)  (5)   (6)

Sets True/False Status Indicator

Normally, the READNEXT statement sets the next status indicator to F or T depending on whether the end of the file is or is not reached, respectively.

If an END AT statement is executed before a READNEXT, the status indicator is also set to F if the record read has a key value beyond the one specified in the END AT statement. Note that the current record area contains the record that is beyond the END AT range and that, unlike an end-of-file condition, the position in the key path does not become undefined.

If the READNEXT sets the next status indicator to F, the FAIL or (FT) parameter determines what additional action to take. In addition, on a false condition, the predefined field STATUS CODE returns a token indicating the reason for an I/O command failure. This token can be used as a key to read the system message file to obtain a descriptive I/O error message (see STATUS CODE for details).

Using the Statement

When using this statement in conjunction with an RDBMS table, you can specify a field name instead of a file name to limit the volume of data being passed between APPX and the RDBMS. See the Partial-Record I/O section in Chapter 4-3: Specifying Statements for more information.

If a key path is specified, the next record is read using the path specified. If no keypath is specified, the keypath used by the most recently executed READ or READNEXT statement for the same file is used. If no READ or READNEXT statement for the same file was previously executed, or the file was logically closed and reopened, the primary key path is used.

If a BEG AT statement for this file is executed before the READNEXT, the position in the file is modified before executing the READNEXT, based on the value and relation specified in the BEG AT statement and the keypath identified by the READNEXT statement.

If the READNEXT identifies a key path that is different than the key path used in the most recently encountered READ or READNEXT statement for the same file, and no subsequent BEG AT is encountered, the file position is reset to the first record in the key path specified in the READNEXT statement.

The key path and position established by the process interpreter for the process control file has no effect on, and is not affected by, the READNEXT position, nor does the key path and position established for a “Read Next Record” loop have any effect.

The READNEXT statement allows a record to be read and held for update. While a record is held, no other user may update or delete that record. If the record is to be rewritten or deleted, the HOLD specification must be set to 1 (hold) or 2 (recover). Otherwise, it should be set to 0 (no). The recover specification holds the record and internally saves a copy of the record so that a subsequent rewrite or delete can be performed, even if the hold is lost (by reading another record with hold before completing the rewrite or delete). “Recover” can rehold the record for update, as long as the saved copy is identical to the original record that was read. Note that performance is improved with hold type 1.

Note also that the READNEXT statement does not generate an “In Use” message if the record to be held is currently being held by another user. The READNEXT statement waits until the record to be read is freed up by the other user, unless a TIMEOUT statement with a nonblank label was previously encountered. In that case, processing control transfers to the specified label.

Restrictions

For consecutive files, the key field must be left blank because there is only one path (the relative record number) for accessing consecutive files.

The READNEXT statement cannot be used with one-record files.

Execution Errors

Once the end of the file is reached, the current position within the file becomes undefined, and a subsequent READNEXT will result in a non-recoverable runtime error unless a position is re-established (see the Sets True/False Status Indicator section above).

Related Statements

BEG AT, END AT, READ, TIMEOUT

Example

In the following example, a range of records is read from the Transaction file and summed into the field, WORK CUSTOMER BALANCE. When the range of records is exhausted, the predefined field A is then set to the balance.

          BEG AT   TAR TRANSACT IN TAR WORK APPLY TO KEY
          END AT   TAR TRANSACT IN TAR WORK APPLY TO KEY
          LABEL    :NEXT TRANSACTION RECORD
          READNEXT TAR TRANSACT               HOLD 0 FT 0 BY TRANSACT KEY
    T     COMPUTE  TAR WORK CUSTOMER BALANCE      +  TAR TRANSACT AMOUNT
    T     GOTO     :NEXT TRANSACTION RECORD
          SET      --- A                          EQ TAR WORK CUSTOMER BALANCE