The READ statement reads a record from a specified file, using the specified key.
HOLD FT BY
(1) (2) (3) (4) (5) (6)
(2) Application ID
(4) Hold type (0=do not hold, 1=hold, 2=hold with potential recovery)
(5) Fail Type (0=nothing, 1=warning, 2=error, 3=cancel)
(6) Access key field name (blank if one-record file)
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).
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.
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.
If any of the above restrictions fail, an error is generated at compile time.
BEG READ, CLOSE, DELETE, END READ, OPEN, READNEXT, REWRITE, TIMEOUT
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.
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).
1 FT 0 BY
F CANCEL Accounts Receivable Parameters Record Not on File