fllogosm
 Main
 User's Guide
 Developer's Guide
 Admin's Guide
 FAQ
 License Info
 Feedback
 BPlusTree

The nrio.BPlusTree class provides a platform-independent, disk-based implementation of B+Trees. You don't need to go through this page, if all you need is using B+Tree indexing on your (J)RXDbase databases, because the forementioned classes can already seamlessly handle B+Trees.

On the other hand, if your own application needs disk-based B+Trees, this page is for you.

The default return strings for the methods presented below are:
READY: (no errors)
WEIRD ERROR: (bug catcher)
NO SUCH ITEM: (can't perform operation: item doesn't exist)
FILE ACCESS PROBLEMS: (something weird at file access level)
SYNTAX ERROR: (wrong parameters?)

Unless stated otherwise. More error codes will be introduced as
BPlusTree will be enhanced.

As of today the following methods are implemented:

 o BPlusTree
        Constructor.
 o
add
        Adds an item to the B+Tree.
 o
delete
        Deletes an item from the B+Tree.
 o
find
        Finds one or more items, using filters.
 o modify
        Modifies an item in the B+Tree.
 o
shutDownBPlusTree
        Closes files and shuts down the B+Tree.
 o thereIsAlready
        Checks for the presence of an entry in the B+Tree.
 o getDuplicatesAllowed
        Checks if it's possible to have duplicate entries in the B+Tree.
 o getLeafIdxName
        Retrieves the file name for the currently in use leaf index file.
 o getNodeIdxName
        Retrieves the file name for the currently in use node index file.
 o getStatus
        Retrieves the status of the B+Tree.
 o setDuplicatesAllowed
        Sets information about duplicate entries in the B+Tree.

nrio.BPlusTree BPlusTree(Rexx dir, Rexx fName, Rexx len, Rexx num)

This is the only constructor available for the BPlusTree object. It creates two files, if necessary, and initializes the object. The two files are named dir+fName+other_chars.lix (for leaves) and dir+fName+other_chars.nix (for internal nodes). You can omit, or include, the platform dependent final path separator in the "dir" parameter.

The parameters are:

dir -- directory where this B+Tree will be stored.
fName -- a name for the B+Tree.
len -- the maximum length for the keys to be stored.
num -- a positive, integer number; it is used by RXDbase and this means that you can safely pass whatever number you like (eg, '1') if you're not using RXDbase.

Rexx add(Rexx item, Rexx index)

This method adds an item to the B+Tree, specifying that its database position is 'index'. If you don't need the extra information provided by 'index', just pass whatever value you like for it.

Rexx delete(Rexx item, Rexx index)

This method deletes one item from the B+Tree.

Rexx find(Rexx filter)

This method executes a query on the BPlusTree.

Valid filter conditions are:
[operator] [value]

Where [operator] can be one of the following: =,<>,>,>=,<,<=
[value] is a valid value for the B+Tree, e.g. 'Robert' if you're storing names.

Wildcards are allowed only for the = and <> operators, and they are represented by the symbol '*', which means "every number of any character". So, Ro* can be Robert, Ronald, etc. *t can be Matt, Robert, etc.
M*t can be Matt, mount, etc. (The search is always case-insensitive)
You can use only one '*' on a given filter (e.g. you can't query for "= *u*i*l*"), with the notable exception of the form *value*, which means "find a substring anywhere that is equal to 'value'".
Example: "= *555*" will search for all the numbers with a 555 in them.

Note: there must be one or more spaces between [operator] and [value].

The returned Rexx string is structured this way:
element [0] is the number of records in the B+Tree that satisfy the filter condition.
Element[n] is the n-th (ranging from 1 to element[0]) record found.

Returned elements represent the "index" parameter sent during the add operation, and are ordered alphabetically (not on the index, but on the item, as one would expect from a B+Tree).

Rexx modify(Rexx oldItem, Rexx index, Rexx newItem)

This method modifies one item from the B+Tree: oldItem, with the index 'index', becomes newItem.

Rexx shutDownBPlusTree()

This method shuts down the B+Tree, doing all necessary cleanup. Call it before shutting down your application.

Rexx thereIsAlready(Rexx item)

This method looks for the presence of item 'item'. It returns '1' if the item is already present, '0' otherwise.

Rexx getDuplicatesAllowed()

This method returns '1' if it is possible to store more than one item with the same key value, '0' otherwise.

Rexx getLeafIdxName()

This method returns the file name of the leaves file (complete with path information, in a machine-dependent format).

Rexx getNodeIdxName()

This method returns the file name of the nodes file (complete with path information, in a machine-dependent format).

Rexx getStatus()

This method returns the B+Tree status.

setDuplicatesAllowed(Rexx allowed)

Call with method with 'allowed' set to '1' if you want to let the users store more than one item with the same key value, '0' otherwise.
Note: the method will only work on subsequent calls of the
modify and add methods -- this means that you can switch from duplicates 'allowed' to 'not allowed' (and back) anytime you want.