B-TREE-P error messages

The message Already inserted! will be displayed by the BTPINS subroutine when it detects an attempt to insert an item identifier that is already in a B-tree. This error is non-fatal, and BTPINS simply returns without attempting the insertion.

Similarly, BTPDEL will display Already deleted! when it detects an attempt to delete an item identifier that is not in a B-tree. This error is also non-fatal, and BTPDEL returns without attempting the deletion.

All other errors detected by the B-TREE-P subroutines cause the execution of a STOP statement, which causes the display of the message ERRMSG [BTPx], where x is a number from 1 to 24.

ERRMSG [BTP7] is caused by using a B-tree name that does not have a corresponding CASE statement in the BTPKEY subroutine.

ERRMSG [BTP8] is caused by calling BTPFIND with an invalid B-tree name in that routine's first argument.

ERRMSG [BTP11] is caused by calling BTPSEQ with a node number in that routine's second argument that was not set by a previous call to BTPFIND.

ERRMSG [BTP15] is caused by calling BTPDEL with an invalid B-tree name in that routine's first argument.

All other BTP numbers in ERRMSG displays are caused by B-trees with inconsistent or damaged data that prevent the B-TREE-P subroutines from operating properly. The only solution is to delete the offending B-tree and rebuild it from scratch with a utility program like the BUILD example, after identifying and correcting the cause of the damage to prevent it from happening again.

Like all files in a multiuser environment, B-tree data can deteriorate if access is not properly programmed and syncronized. Damaged B-trees are easily prevented by following these rules:

    • Use only one node size for each B-tree.
    • Every time a new item is created in a data file, use BTPINS to insert the item's identifier in the B-tree.
    • Any time an item's data is changed, use BTPDEL and the old version of the item to remove its B-tree entry if the data being changed is referenced by BTPKEY. Then use BTPINS and the new item data to reinsert the item's identifier in the B-tree.
    • Any time an item is deleted from the data file, use BTPDEL and the last filed version of the item to remove its B-tree entry. The arguments of a BTPDEL call to delete a B-tree entry should always exactly match what the arguments were when the entry was inserted with BTPINS.
    • A B-tree file can hold any number of B-trees, each with a different name, and each B-tree contains the identifiers of items from only one data file. Item identifiers from different data files can not be inserted into the same B-tree.
    • Use LOCK and UNLOCK statements to prevent multiple users from simultaneously changing the same B-tree with BTPINS or BTPDEL.
    • Use BREAK OFF and ON statements to prevent users from terminating an update program after the B-tree has been adjusted but before the data file is written.