Key-Field-Value Specifier (VMS only)

7.1.1.7 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 attributes of a key field are information such as the number, direction, length, byte offset, and type of the field. The key field can be used to access records in indexed files because it determines their location.

The attributes of the key field are specified at file creation. Records in an indexed file have the same attributes for their key fields.

Key-field-value specifiers have two components:

An expression val that specifies a value used to compare with key-field values.
A selection condition keyword (such as KEY) that specifies how to compare val with key-field values.

These specifiers take the following forms:

Ascending Keys	Descending Keys
KEY = val	KEY = val
KEYEQ = val	KEYEQ = val
KEYNXT = val	KEYNXT = val
KEYNXTNE = val	KEYNXTNE = val
KEYGT = val	KEYLT = val
KEYGE = val	KEYLE = 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. (On OpenVMS systems on Alpha processors, you can define INTEGER*8 keys.)

The Selection Condition

The selection condition determines how val is compared with key-field values. The keyword can be any one of the following specifiers:

Ascending Keys

KEY and KEYEQ: The value in the key field must be equal to val.
KEYNXT: The value in the key field must be the next value of the key equal to or greater than val.
KEYNXTNE: The value in the key field must be the next value of the key strictly greater than val.
KEYGT: The value in the key field must be greater than val.
KEYGE: The value in the key field must be greater than or equal to val.

Descending Keys

KEY and KEYEQ: The value in the key field must be equal to val.
KEYNXT: The value in the key field must be the next value of the key equal to or less than val.
KEYNXTNE: The value in the key field must be the next value of the key that is strictly less than val.
KEYLT: The value in the key field must be less than val.
KEYLE: The value in the key field must be less than or equal to val.

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

	In Ascending-Key Files	In Descending-Key Files
Specifier:	Is Equivalent to Specifier:
KEYNXT	KEYGE	KEYLE
KEYNXTNE	KEYGT	KEYLT

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 results in a run-time error.

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 by using the signed integers themselves.

To select key-field character values, the process compares values by using the ASCII collating sequence. (Other collating sequences are available. For more information, see the Guide to OpenVMS File Applications.) The comparative length of val and a key-field value, as well as the specified selection condition, determine the kind of selection that occurs: exact, generic, or approximate-generic.

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 keyword specifies a unique selection.

Generic selections occur when the expression in val is shorter than the expression in the key field of the currently accessed record and the keyword specifies a unique selection. 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, if val is 'ABCD' and a record's key-field is 10 characters long, and you specified an equal selection, the process could select a record with a key-field value 'ABCDEFGHIJ'.

An approximate-generic selection occurs when val is shorter than the expression in the key field and the keyword (KEYGT, KEYGE, KEYLT, KEYLE, KEYNXT, and KEYNXTNE) does not specify a unique selection. 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, if val is 'ABCD' and a record's key-field value is 5 characters long and you specify a greater-than selection, the process could select the key-field value 'ABCEx' (and not the key-field value 'ABCDA').

No selection occurs if val is longer than the key-field value. The result is a run-time error.

Previous Page Next Page Table of Contents