READ

The READ statement reads a record from a specified file, using the specified key.

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

Sets True/False Status Indicator

The next status indicator is set to T if the record is read successfully, and to F if the record is not found. If the record is not on file, 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.

The READ statement allows a record to be read as “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 parameter 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 READ statement does not generate an “In Use” message if the record to be read as “held” is currently being held by another user. The READ statement simply waits until the record to read has been freed up by the other user, unless a TIMEOUT statement with a nonblank label was previously encountered. If a TIMEOUT statement is used, processing control transfers to the specified label.

The keypath and position established by the process interpreter for the process control file is not affected by a “Read Next Record” loop.

Restrictions

The contents of a specified key field must be set before executing a READ. For one-record files, the key field specification must be left blank. For consecutive files, the key field specification must contain a numeric field that must be set to the relative record number of the record to be read, or a numeric constant indicating that record number. For indexed files, the key field specification must identify a key field in the file to be read.

Compilation Errors

If any of the above restrictions fail, an error is generated at compile time.

Related Statements

BEG READ, CLOSE, DELETE, END READ, OPEN, READNEXT, REWRITE, TIMEOUT

Example

In the following example, the original transaction date is set from the Unpaid Invoices file if a record exists for that invoice, or from the Cash Receipts file if no such record is found.

          *        Set original transaction date so post can compute days to pay
          SET      TAR UNPAID CUSTOMER NO         =  TAR RECEIPT2 CUSTOMER NO
          SET      TAR UNPAID APPLY TO            =  TAR RECEIPT3 PAID INVOICE
          READ     TAR UNPAID                 HOLD 0 FT 0 BY UNPAID KEY
    T     SET      TAR POST ORIGINAL TRX DATE     =  TAR UNPAID INVOICE DATE
    F     SET      TAR POST ORIGINAL TRX DATE     =  TAR RECEIPT2 DATE RECEIVED

In the second example below, the Accounts Receivable Parameters record is read for update and the process is canceled if the record is not found (no key is specified because Parameters is a one-record file).

          READ     TAR PARAM                  HOLD 1 FT 0 BY
    F     CANCEL   Accounts Receivable Parameters Record Not on File