FIND

Find a record

FIND(channel[, record][, key_spec][, GETRFA:new_rfa][, KEYNUM:krf_spec]
&   [, LOCK:lock_spec][, MATCH:match_spec][, POSITION:pos_spec]
&   [, RFA:match_rfa][, WAIT:wait_spec]) [[error_list]]

Arguments

channel

The channel on which the file is open. The channel must already have been opened in input or update mode. (n)

record

(optional) The record area that, for non-OpenVMS, non-ISAM files, determines the record size. Record is required for non-ISAM files and optional for ISAM files. Since OpenVMS files always have a record size, record is never required on OpenVMS. (a)

key_spec

(optional) Either an expression whose result is the key to find, the ordinal record number for relative files, or one of the following options:

^FIRST = Position to the first record in the file.

^LAST = Position to the last record in the file.

On Windows and UNIX, ^LAST works only on ISAM and relative files. On OpenVMS, ^LAST works only on ISAM files.

GETRFA

(optional) Returns the record’s RFA. See GETRFA for a complete description.

KEYNUM

(optional) Specifies a key of reference by which to perform FIND for ISAM files. See KEYNUM for a complete description.

LOCK

(optional) Specifies whether the record is to be locked. See LOCK for a complete description.

MATCH

(optional) Defines how a specified key is matched. See MATCH for a complete description.

POSITION

(optional) Specifies an absolute position in the file. See POSITION for a complete description.

RFA

(optional) Finds the record with the specified RFA. See RFA for a complete description.

WAIT

(optional) Specifies how long to wait for a record lock to be released. See WAIT for a complete description.

error_list

(optional) An I/O error list. If any one of the specified errors occurs as part of the FIND, control is transferred to the associated label.

Discussion

The FIND statement positions to a record that can be retrieved by the next READS statement. It is functionally similar to the READ statement, except that FIND does not retrieve the record from the file; it only sets a pointer to that record so that it can be retrieved by the next READS statement. The READS statement must be the next I/O operation on the same channel. (DIRECTION and REVERSE qualifiers on that READS statement are ignored.)

FIND does not lock the record unless you specify the LOCK qualifier or compile with the FIND lock compiler option (/find_lock on OpenVMS or -F on all other systems).

The record to position to is specified either by absolute position (^FIRST, ^LAST, or the POSITION qualifier), the MATCH qualifier (valid on ISAM files only), the RFA qualifier, or key_spec in the following order of precedence:

If absolute position is specified, MATCH, RFA, and key_spec are ignored, unless POSITION:Q_IGNPOS is specified.

If the MATCH qualifier is specified, the RFA qualifier is ignored, unless MATCH:Q_RFA is specified. Key_spec is also ignored if MATCH:Q_RFA or MATCH:Q_SEQ is specified.

If absolute position is not specified but RFA is, key_spec is ignored.

If absolute position, MATCH, and RFA qualifiers are not specified, key_spec defines the record to position to, with the key of reference determined either by KEYNUM or the logic described in step 2.

If you specify a numeric key value in key_spec (d or i) and the file's defined key is also numeric (d, i, or u), the value will be converted to the appropriate type and length to locate the record. Otherwise, if either the key value or defined key is non-numeric (implied or segmented), and you specify a key value in key_spec whose length is greater than the file's defined key, only the first part of the key value locates the record. If the key value length is less than the size of the file's defined key, the value is called a partial key. In this case, the record located will be the first one that has a key that begins with the specified value.

If only one record/key_spec is specified, it is interpreted as key_spec.

The key of reference is determined as follows:

If the KEYNUM qualifier is specified, it defines the key of reference.
If KEYNUM is not specified, FIND uses the implied key of reference. The implied key of reference is a field within record that matches the offset and contiguous length of the key defined by key_spec. If a match is not found, the first key that matches the offset and has a greater length than key_spec is the implied key of reference.
If KEYNUM is not specified and the conditions for an implied key of reference do not exist, FIND uses the primary key as the key of reference if system option #45 is not set.

We recommend that you use the KEYNUM option rather than relying on the implied key of reference; KEYNUM is more efficient.

On OpenVMS, if you specify both the RFA and KEYNUM qualifiers on the FIND statement, KEYNUM must specify the primary key as the key of reference (Q_PRIMARY or 0).

For ISAM files, if the MATCH qualifier is not specified, FIND matches on values greater than or equal to the specified value. If no record’s key field begins exactly as specified by the key value, the first record with a higher key value is located, and a “Key not same” error ($ERR_KEYNOT) occurs. If no higher record exists, an “End of file” error ($ERR_EOF) occurs.

If you want to FIND a segmented key that is specified by key_spec in an ISAM file, you must first construct that key by concatenating each segment together. You can use the %KEYVAL function to return the extracted key value from the specified record.

The syntax

find(channel, ..., ^LAST)

is deprecated. Use the POSITION I/O qualifier instead.

See the note under Record locking for information about inconsistencies that may occur after an I/O error is encountered.