KEY(),KEYF(),KEYL(),KEYN(),KEYP() - File Key Functions

Syntax

KEY(channelno{,ERR=lineref}{,END=lineref}{,IND=index}{,KNUM=int})

KEYF(channelno{,ERR=lineref}{,END=lineref}{,IND=index})

Description

For BBj-specific information, see the KEY(),KEYF(),KEYL(),KEYN(),KEYP() - File Key Functions.

The KEY() functions return keys from DIRECT, SORT, or MKEYED files opened on the given channel.

• KEY() returns the key at the current file pointer position in the file. For TCP/IP and UDP sockets, it returns the IP of connected machine or last received packet.

• KEYF() returns the first logical, or lowest, key in the file. For TCP/IP and UDP sockets, it returns the port signature "IP;port;hostname". Servers will not have an IP or hostname.

• KEYL() returns the last logical, or greatest, key in the file.

• KEYN() returns the key following the current key (next key).

• KEYP() returns the key prior to the current key.

Parameter	Description
channelno	Valid channel number.
ERR=lineref	Branch to be taken if an error occurs during execution.
END=lineref	Branch to be taken at end-of-file (!ERROR=2). END= overrides ERR= for end-of-file cases.
IND=index	Index specifying the temporary location of the file pointer for the duration of the function. Errors may occur if the file pointer is moved beyond the end of the file. If the file pointer is moved to a deleted key, the KEY() function returns a string of $FF$s and the KEYP() and KEYN() functions issue an end-of-file error. NOTE: The IND= option will not function with MKEYED files. It is intended for utility purposes only and should not be used in an application program.
KNUM=int	MKEYED file chain. This option works only with the KEY() function. Using KNUM= in the KEY() function does not change the KNUM used for READ or WRITE.

When a key is returned, each trailing $00$ is stripped off. A varying length key may be returned.

An end-of-file error (!ERROR=2) may occur when attempting to:

• KEY() or KEYN() is used when the file pointer is at end-of-file.

• Any KEY() function is used on an empty file.

• KEYP() is used at the beginning of the file.

• KEYN() is used when the file pointer is at the last record in a file.

C-ISAM File Behavior

Listed below are some important behaviors for C-ISAM files:

• If the first or last record in a key chain is removed by another user or process, it is possible that a KEYF() or KEYL() function may not execute correctly.

• The FIND verb resets the file pointer. Subsequent KEYF() and KEYL() functions can result in !ERROR=2.

Examples

>PRINT KEY(CHANNEL)
0010001234
>PRINT KEY(CHANNEL2)
0X100ENTRY
20100 LET ACCOUNT$=KEY(3,END=6200)

If a FILE has seven keys from 1 to 7, and the pointer is at the fourth key, the functions return the following results:

	Keys	Key Functions
	1 <-	KEYF
	2
	3 <-	KEYP
Pointer	4 <-	KEY
	5 <-	KEYN
	6
	7 <-	KEYL

Following a READ(1, KEY=A$), the KEYP() function returns the key of the record just returned.

See Also

Functions - Alphabetical Listing