Using Lookup and Browse Routines

BTREEs provide two routines usually used to access the key files. These two routines provide an interactive browsing interface used to search for a record using the sorted keys. The routines feature the following:
Forward/backward scrolling along sorted key paths.
Formatted columnar displays. These displays are defined using the key definition utility and can consist of columns containing any data within the data file plus data from other files via the translate conversion functions.
Single key selection of items.
Keyboard look-ahead allowing you to select an item or scroll the display forward or backward while the screen is still being updated.

KEY.LOOKUP Subroutine

The KEY.LOOKUP( ) subroutine is used to perform a generalized lookup function allowing you to search for a record using any defined key path. The subroutine can be used anywhere that you would have been prompted to enter the item-ID of the desired record.

Format

CALL KEY.LOOKUP(file.var,id,data,error)

Parameter(s)

file.var	File variable into which the desired file has been OPENed using the mvBASIC OPEN statement. If the file does not have any keys defined, this routine will simply prompt for an item-ID.
id	Item-ID of the selected record.
data	Dynamic Array containing the data from the selected record or NULL if the selected record is not on file.
error	Normally NULL, but may contain the word ABORT if you abandoned the lookup function without making a selection or entering an item-ID.

The KEY.LOOKUP( ) subroutine operates as follows:

Clears the screen.
Displays the name of the file.
Prompts you to enter the desired item-ID, press ENTER to use one of the lookup keys.
If you enter an item-ID, the subroutine will return the item-ID to the calling program along with the item’s dynamic array, if the item was on file.
If you press ENTER, you are prompted with a display of the available keys that may be used for searches. Enter a key number, press ENTER to enter the item-ID again, or X to exit the function. Typing X returns ABORT as the error status.
If you selected a key, you are prompted to enter the starting key value. Pressing ENTER returns you to the enter item-ID stage of the lookup function.
If you do enter a key starting value, the key file is searched for the specified value and a full-screen display from that value forward displays in columnar format. The left-most edge of the display are letters from A-S (for a 24 line screen). These letters may be used to select a displayed record. Additionally these keys are active:

Key	Action
+	Scroll a page forward.
<CR>	Scroll a page forward.
-	Scroll a page backward.
0	Return to the item-ID entry step.

If the beginning or end of file is reached, an appropriate message displays and you return to the item-ID entry step.

KEY.SCROLL Subroutine

The KEY.SCROLL( ) lookup subroutine is a slightly lower level interface allowing your application program to specify the key involved as well as the starting key value. It can be more versatile than the KEY.LOOKUP( ) subroutine but does require more setup from within your application program.

Format

KEY.SCROLL(file.var,y0,y1,key.name,key.val,id,data,error)

Parameter(s)

file.var	Variable to which a keyed file has been opened.
y0	Top of the window in which the lookup function is to operate.
y1	Bottom of the window in which the lookup function is to operate.
key.name	Name of the BTREE key that is to be searched.
key.val	Beginning value being searched.
id	The selected item-ID or NULL if no item is selected.
data	A Dynamic Array of the data from the selected item or NULL if no item is selected.
error	Normally NULL. The word ABORT will be returned if you exit the lookup function without making a selection.

The KEY.SCROLL( ) subroutine functions in the same way as the KEY.LOOKUP( ) subroutine with respect to end-user operation.