MATCH

Define how a record is located

MATCH:match_spec

Arguments

match_spec

One of the following identifiers or values: (n)

Q_GEQ or 0

Locate the record that matches the key value greater than or equal to the key specification. If no equal match is found, the next greater record is read (and locked if record locking is enabled) and a “Key not same” error ($ERR_KEYNOT) is generated. If no greater record exists, an end-of-file occurs. (default)

Q_EQ or 1

Locate the record that matches the key value equal to the key specification. If no match is found that is equal to the key specification, a “Record not found” error ($ERR_RNF) occurs.

Q_GTR or 2

Locate the record that matches the key value greater than the key specification. No error occurs unless end-of-file is reached, in which case, an “End of file” error ($ERR_EOF) occurs.

Q_RFA or 3

Locate the record with the RFA specified by the RFA qualifier.

Q_GEN or 4

Locate the record that matches the key value that is equal or next in sequence to the key specification. An “End of file” error ($ERR_EOF) is generated if there are no matches nor any higher records in sequence.

Q_SEQ or 5

Locate the next sequential record following the current record, ignoring the key specification. No error occurs unless end-of-file is reached.

Discussion

The MATCH qualifier is only supported for ISAM files.

The MATCH qualifier defines how a record is located in an ISAM file. It uses relative relationships (for example, greater than and greater than or equal to) to make this determination.

The record that is read is the first one that logically follows key_spec according to the collating sequence of the index of reference (i.e., whether the key is sorted ascending or descending). For example, if you have a key ordered ascending, a greater-than match retrieves the next higher key value. However, if the key is ordered descending, a greater-than match retrieves the next lower key value.

The record retrieved by a READS after a READ with MATCH:Q_EQ that returns a “Record not found” error ($ERR_RNF) is different on OpenVMS and non-OpenVMS systems. On non-OpenVMS systems, a subsequent READS will read the next higher record. On OpenVMS, the current record context is not changed and you must use READ or FIND to re-establish context.