Sizing Key Files

Key files are data files just like any other files and must have appropriate modules to operate correctly. The host’s file resizing functions automatically resize key files in the same manner as other data files.

mvBASIC BTREE Interfaces

mvBASIC statements and functions are supplied to access the BTREE key files directly. The BTREE key file contains key elements that are actually a concatenation of the computed key along with the item-ID. The two elements are separated by a single character delimiter which is a CHAR(1). Use of this character ensures that the key elements will sort in the proper order. If you utilize the low-level BTREE routines that return the key, you can use a statement similar to the following in order to extract the item-ID from the key:

ID = FIELD(KEY,CHAR(1),2)

If the key structure is also MultiValued, the value number may be extracted with:

VAL.NO = FIELD(KEY,CHAR(253),3)

VAL. NO = KEY<1,3>

Also, the function called KEYIDS( ) extracts the item-IDs from a multiattribute list.

NXTKEY Statement

The NXTKEY statement scans forward through a key file along a key path.

Format

NXTKEY result FROM filevar,keyname,key,n THEN/ELSE

Parameter(s)

result	Returned variable containing the keys retrieved in a multiattribute dynamic array.
filevar	Variable to which the data file has been opened.
keyname	Name of the key to retrieve along.
key	Beginning key value at which to begin the retrieval.
n	Number of keys to retrieve.

This statement retrieves at most n keys. Fewer may be retrieved if end-of-file is reached.

Repetitive use of this statement is allowed with the last key from the previous statement being supplied as the beginning key for the next statement.

The ELSE clause is executed if the file is not a keyed file or if the specified keyname is invalid. If the ELSE clause executes, then SYSTEM(0) returns the error condition as:

0	File was not a keyed file.
1	Keyname was invalid.

PRVKEY Statement

The PRVKEY statement operates in the same manner as the NXTKEY statement with the exception that the keys returned are those previous to the beginning key value key.

Format

PRVKEY result FROM filevar,keyname,key,n THEN/ELSE

Also, the keys are returned in what may be viewed as reverse order and a short list is due to a beginning file condition.

KEYIDS Function

KEYIDS( ) returns a multiattribute list of item-IDs when supplied the multiattribute result variable from either the NXTKEY or PRVKEY statements. It is considerably faster than extracting the item-IDs one at a time and additionally lends itself to using the mvBASIC SELECT statement to process the item-IDs one at a time.

Querying the Key Structure

The KEYSTRUCT( ) function queries the index structure for a particular file. This allows applications to utilize keys that are available for a file without necessarily being programmed for that specific file.

Format

KEYSTRUCT(file.var)

KEYSTRUCT( ) returns a dynamic array that describes all of the indexes that are defined for the file that has been opened to file.var. If the returned string is null, then the file does not have any defined keys.

The returned dynamic array has one attribute for each key that is defined. The keys are stored in alphabetical order by keyname. Within each key’s attribute are MultiValues that describe the individual key’s structure. These MultiValues are:

Value No.	Description
001	Keyname.
002	Key optimizing parameter.
003	Multisubvalue list of attributes that are MultiValued for this particular key.
004	Stack equation used to compute the key value.
005	Stack equation used to compute the default display columns for the BT.LOOKUP and BT.SCROLL subroutines.
006	String which is the heading for the BT.LOOKUP and BT.SCROLL subroutines.
007	Lookup function ICONV.

Sample program using KEYSTRUCT( ):

OPEN ‘CUSTOMERS’ TO CUST.FILE ELSE STOP 201,‘CUSTOMERS’

A = KEYSTRUCT(CUST.FILE)

IF A = ‘’ THEN

PRINT ‘CUSTOMERS FILE HAS NO BTREES KEYS’

END ELSE

PRINT ‘CUSTOMER FILE HAS ’ : DCOUNT(A,CHAR(254)) : ‘KEYS’

END