KEY

Key Value

This string function returns the key value for the next sequential record in a DIRECT or SORT file OPEN on the specified channel.

Syntax

KEY (channel [, SRT=sort-name] [, END=line-ref]
[,ERR=line-ref|,ERC=error-code])

channel

is an integer in the range of 0 to 32764 specifying the channel number of an OPEN file.

sort-name

is any string of 20 characters or fewer that specifies the name of a sort sequence in an MSORT file; if not specified, the current sort sequence is used. Specifying a sort-name other than the current sort sequence does not change the current sort sequence for [P]READ and [P]EXTRACT.

line-ref

is the program line number or label to branch to if an error (ERR=) or end of file (END=) occurs while processing this function.

error-code

is a programmer-defined error code. Valid values are positive or negative whole numbers.

Remarks

The SRT= option is only valid for MSORT files. Specifying SRT= does not alter the currently active sort key for [P]READ and [P]EXTRACT, but provides the ability to obtain the values for other sort keys from the next sequential record based on key.

Reference to the KEY function does not update the record pointer to the next key value.

The KEY function is updated by any successful I/O directive.

This function cannot be directly used in an I/O directive; it must first be assigned to a string variable.

If an attempt is made to obtain the KEY of a channel which is not OPEN to a key-access file, an ERR=13 results.

If an attempt is made to obtain the KEY of the next record when the current record is the last in the file, an ERR=2 results.

If an attempt is made to obtain the KEY of a channel which is not OPEN, an ERR=13 results.

Examples

LET KEY$ = KEY (1)

If KEY$ is assigned the value “ABC”, then the next record to be READ or INPUT on channel 1 has a key value of “ABC”.

LET X$ = KEY (1, ERR=7999)

returns the key value for the next record and branches to statement 7999 if an error occurs while processing this function.

See also

FKY, LKY, and PKY functions
EXTRACT, FIND, INPUT, PRINT, READ, and WRITE directives

From the Thoroughbred Basic Language Reference, Volume II: F–Q, version 8.9.1. Open this page in the PDF