BEG READ

The BEG READ statement initiates a “Read Next Record” loop, in which the next record that meets any previously specified range criteria is read. You end the loop with an END READ statement for the same file. Usually, you precede a BEG READ statement with a BEG AT and/or an END AT statement to specify the range of records to be read.

    ••••• BEG READ ••• •••••••••••••••••••••• HOLD • KEY IS  ••••••••••••••••••••••
    (1)            (2) (3)                        (4)        (5)

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.

When using a BEG READ statement, you specify whether the record is to be held for updating. If no update is to occur, enter 0; if updating is possible or mandatory, enter 1; if you want to hold the record for potential recovery, enter a 2. While a record is held, no other user may update or delete it. The HOLD with potential recovery specification holds the record and saves a copy of it so that a subsequent rewrite or delete can be performed, even if the hold on the record is subsequently lost (by reading another record with hold before completing the rewrite or delete). “Recover” can rehold the record as long as the saved copy is identical to the original record that was read. Note that performance is improved with hold type 1.

You can specify a keypath for indexed files that will serve as the access path to the file. If you leave this parameter blank, the primary key is used.

Records are read until the specified key has a value larger than the value of the field specified in the last END AT statement for the file. For sequential files, records are read until the relative record number for the file is larger than the record number specified in the last END AT statement for the file. If no END AT was executed, the “Read Next Record” loop is repeated until an end-of-file condition occurs.

Execution continues with the statement following the corresponding END READ statement if:

·    The end-of-file is reached,

·    A record with a key value greater than that specified in the last END AT statement is read, or

·    There were no records in the specified range.

If a “Read Next Record” loop terminates for any reason, the record area contains the record that is causing the loop to end.

The file position that you can define by BEG AT/END AT, and maintained and used by the BEG READ “Read Next Record” loop, is unique to that specific “Read Next Record” loop. If the file being read by the “Read Next Record” loop is accessed within the loop by other file-access statements, the file position will not be affected when the END READ is executed. For example:

          BEG AT   TAR CUSTOMER IN     2
          END AT   TAR CUSTOMER IN     7
          BEG READ TAR CUSTOMER               HOLD 0 KEY IS  CUSTOMER NO
          SET      TAR CUSTOMER NO                =      10
          READ     TAR CUSTOMER               HOLD 0 FT 0 BY CUSTOMER NO
          END READ TAR CUSTOMER

Customer 10 is outside of the range set up by BEG AT/END AT but the READ statement will be successful (assuming the customer 10 record is on file) because the range specified applies only to the BEG READ “Read Next Record” loop. When the END READ executes, the file is repositioned to read the next record in the logical range for the “Read Next Record” loop.

Assuming all customer records are on file, the looping logic for this example is:

·    BEG READ reads the customer 2 record,

·    READ reads the customer 10 record,

·    END READ reads the customer 3 record and returns control to the statement immediately following BEG READ,

·    READ reads the customer 10 record,

·    END READ reads the customer 4 record,

and so on, until the customer 8 record is read, which ends the loop. Processing then continues with the statement following the END READ.

If a READNEXT is executed within the BEG READ “Read Next Record” loop, its position in the file is maintained completely independently of the “Read Next Record” loop. For example:

          BEG AT   TAR CUSTOMER IN     2
          END AT   TAR CUSTOMER IN     4
          BEG READ TAR CUSTOMER               HOLD 0 KEY IS  CUSTOMER NO
          READNEXT TAR CUSTOMER               HOLD 0 FT 0 BY CUSTOMER NO
          END READ TAR CUSTOMER

Again assuming all customer records are on file, BEG READ reads the customer 2 record. READNEXT reads the customer 1 record (the first record in the file) which is outside the BEG AT/END AT range but, because the range applies only to the BEG READ “Read Next Record” loop, the READNEXT succeeds. END READ reads the customer 3 record because this is the next logical record for the BEG READ “Read Next Record” loop. READNEXT now reads the customer 2 record, the next logical record in its thread. Continuing in this way, END READ reads the customer 4 record, and READNEXT reads the customer 3 record. Finally, END READ reads the customer 5 record, which ends the BEG READ “Read Next Record” loop.

You can also nest BEG READ “Read Next Record” loops within a “Read Next Record” loop. The following example loops through the CUSTOMER file and, for each customer record read, loops through the TRANSACT file records for that customer.

          BEG READ TAR CUSTOMER               HOLD 0 KEY IS  CUSTOMER NO
          BEG AT   TAR TRANSACT IN TAR CUSTOMER NO
          END AT   TAR TRANSACT IN TAR CUSTOMER NO
          BEG READ TAR TRANSACT               HOLD 0 KEY IS  TRANSACT KEY
          *
          *        (process transactions for customer)
          *
          END READ TAR TRANSACT
          *
          *        (process customer information)
          *
          END READ TAR CUSTOMER

Restrictions

For sequential files, you must leave the key field blank. Note that the BEG READ statement does not generate an “In Use” message if the record to be held is currently being held by another user. The BEG READ statement either waits until the record is released or, if a TIMEOUT statement with a nonblank label was previously encountered, transfers processing control to the specified label. You cannot use the BEG READ statement with one-record files.

Compilation Errors

If there is no END READ statement that corresponds to the BEG READ statement, an error occurs at compile time.

Execution Errors

Once the BEG READ “Read Next Record” loop terminates, re-executing an END READ statement without first re-executing a BEG READ generates a fatal file-processing error.

Related Statements

BEG AT, END AT, END READ, READ, READNEXT, TIMEOUT

Example

The following example demonstrates a common use of the BEG READ statement where a range is specified:

          BEG AT   TAR TRANFILE IN TAR CUSTOMER NO
          END AT   TAR TRANFILE IN TAR CUSTOMER NO
          BEG READ TAR TRANFILE               HOLD 0 KEY IS  TRANFILE KEY
          *
          *        (process each TRANFILE record for specified customer)
          *
          END READ TAR TRANFILE

In this example, the system reads the TRANFILE file beginning with the first record where the TRANFILE CUSTOMER NO is equal to or greater than the CUSTOMER NO supplied. (TRANFILE CUSTOMER NO must be the first part of TRANFILE KEY.) The BEG READ “Read Next Record” loop terminates when the TRANFILE CUSTOMER NO exceeds the value specified in the END AT statement. If no BEG AT is present, the read begins with the first record in the file. If no END AT is present, the read continues to the end of the file.