How to use BTPFIND and BTPSEQ

The BTPFIND subroutine is used to determine where item identifiers fall in place in B-trees. Once a position in a B-tree has been determined by BTPFIND, the BTPSEQ subroutine can find the previous or next item identifier. The LIST.NAMES program was the simplest example that showed how BTPFIND and BTPSEQ are called:

    LIST.NAMES
001 OPEN "B-TREE" TO BFILE ELSE STOP
002 OPEN "NAMES" TO NFILE ELSE STOP
003 ID = "" ; ITEM = ""
004 CRT "ZIP, COMP, OR LNAME":
005 INPUT ROOT
006 CALL BTPFIND(ROOT,BFILE,NFILE,ID,ITEM,NODE,POS)
007 LOOP
008   READ NAMES FROM NFILE, ID ELSE NAMES = ""
009   PRINT ; PRINT ID
010   FOR AMC = 1 TO 6
011     LINE = NAMES<AMC>
012     IF LINE # "" THEN PRINT LINE
013   NEXT AMC
014   CALL BTPSEQ(BFILE, NODE, POS, "NEXT", ID)
015 UNTIL ID = "" DO REPEAT
016 STOP
017 END

BTPFIND is called with seven arguments. The first argument can be a constant or variable, and is the name of the B-tree being searched.

The second argument is the file variable the B-tree file was opened to in a previous OPEN statement.

The third argument is the file variable a data file was opened to in a previous OPEN statement.

The fourth and fifth arguments, which must be variables, contain an item identifier and associated data from the data file. BTPFIND finds the position in the B-tree where the item would go. The item identifier and data for the item already in the B-tree at that position are then copied into the fourth and fifth arguments (destroying their previous values), for use by the calling program.

The sixth and seventh arguments, which must be variables, are set to the B-tree node number and node position of the item located by BTPFIND, so that they can be used by the calling program in a subsequent call to BTPSEQ.

A useful trick is to call BTPFIND with a null item identifier and data value (which always appear first in an ascending sort), like the LIST.NAMES example does above. As a result, BTPFIND returns the first item in the sorted B-tree, which is convenient for starting ordered listings of the items in the B-tree, like LIST.NAMES does.

BTPFIND can also be used to locate the item in a B-tree that most closely matches a partial data record, like the BROWSE.NAMES program does. For example, calling BTPFIND with arguments consisting of a null identifier and a NAMES data item containing only a last name with all other attributes null, can find the first item in the LNAME B-tree that has that last name.

Once a node number and node position have been returned by a BTPFIND call, those values can be passed to the BTPSEQ subroutine to obtain the previous or next item identifier in the B-tree, like the LIST.NAMES example does.

BTPSEQ is called with five arguments. The first argument is the same file variable of a B-tree referenced in a previous call to BTPFIND or BTPSEQ.

The second and third arguments must be variables, equal to an item identifier's B-tree node number and node position determined by a previous call to BTPFIND or BTPSEQ.

The fourth argument can be a variable or constant. If the argument is equal to "PREV", BTPSEQ finds the previous item identifier in the B-tree, starting from the given node number and position. Otherwise, the fourth argument is assumed to be "NEXT", and BTPSEQ finds the next item identifier in the B-tree.

The fifth argument must be a variable, and is set by BTPSEQ to the previous or next item identifier it finds in the B-tree. If the beginning or end of the B-tree is reached, the argument is set to null. The second and third argument variables are also set to the new identifier's node number and position. That allows BTPFIND to determine a starting node and position, and BTPSEQ can then be repeatedly called to traverse the rest of the B-tree like LIST.NAMES does, since the results of each call to BTPSEQ can be used as arguments for the next BTPSEQ call.