10.2.1.5 Key-Field-Value Specifier (VMS only)

The key-field-value specifier identifies the key field of a record that you want to access in an indexed file. The key-field value is equal to the contents of a key field. The key field can be used to access records in indexed files because it determines their location.

A key field has attributes, such as the number, direction, length, byte offset, and type of the field. The attributes of the key field are specified at file creation. Records in an indexed file have the same attributes for their key fields.

A key-field-value specifier takes the following form:

KEY[con]=val

con
Is a selection condition keyword specifying how to compare val with key-field values. The keyword can be any of the following:

In Ascending-Key Files:
Keyword	Meaning
EQ	The key-field value must be equal to val. KEYEQ is the same as specifying KEY without the optional con.
GE	The key-field value must be greater than or equal to val.
GT	The key-field value must be greater than val.
NXT	The key-field value must be the next value of the key equal to or greater than val.
NXTNE	The key-field value must be the next value of the key strictly greater than val.
In Descending-Key Files:
Keyword	Meaning
EQ	The key-field value must be equal to val. KEYEQ is the same as specifying KEY without the optional con.
LE	The key-field value must be less than or equal to val.
LT	The key-field value must be less than val.
NXT	The key-field value must be the next value of the key equal to or less than val.
NXTNE	The key-field value must be the next value of the key that is strictly less than val.

val
Is an integer or character expression. The expression must match the type of key defined for the file. For an integer key, you must pass an integer expression; it cannot contain real or complex data. For a character key, you can pass either a CHARACTER expression or a BYTE array that contains CHARACTER data.

The specifiers KEY, KEYEQ, KEYNXT, and KEYNXTNE are interchangeable between ascending-key files and descending-key files. However, KEYNXT and KEYNXTNE are interpreted differently depending on the direction of the keys in the file, as follows:

The specifiers KEYGE and KEYGT can only be used with ascending-key files, while the specifiers KEYLE and KEYLT can only be used with descending-key files. Any other use of these key specifiers causes a run-time error to occur.

When a program must be able to use either ascending-key or descending-key files, you should use KEYNXT and KEYNXTNE.

The Selection Process

To select key-field integer values, the process compares values using the signed integers themselves.

To select key-field character values, the process compares values by using the ASCII collating sequence.¹ The comparative length of val and a key-field value, as well as any specified selection condition, determine the kind of selection that occurs. The selection can be exact, generic, or approximate-generic, as follows:

• Exact selections occur when the expression in val is equal in length to the expression in the key field of the currently accessed record, and the con keyword specifies a unique selection condition.
  
  
• Generic selections occur when the expression in val is shorter than the expression in the key field of the currently accessed record, and the con keyword specifies a unique selection condition.

  The process compares all the characters in val, from left to right, with the same amount of characters in the key field (also from left to right). Remaining key-field characters are ignored.

  For example, consider that a record's key field is 10 characters long and the following statement is entered:

    READ (3, KEYEQ = 'ABCD')
  

  In this case, the process can select a record with a key-field value 'ABCDEFGHIJ'.
• An approximate-generic selection occurs when the expression in val is shorter than the expression in the key field, and the con keyword does not specify a unique selection condition.

  As with generic selections, the process uses only the leftmost characters in the key field to compare values. It selects the first key field that satisfies the generic selection criterion.

  For example, consider that a record's key field is 5 characters long and the following statement is entered:

    READ (3, KEYGT = 'ABCD')
  

  In this case, the process can select the key-field value 'ABCEx' (and not the key-field value 'ABCDA').

If val is longer than the key-field value, no selection is made and a run-time error occurs.

¹ Other collating sequences are available. For more information, see the Guide to OpenVMS File Applications.