The Insert Entry in a Balanced Binary Tree routine inserts a node
    in a balanced binary tree.

    Format

      LIB$INSERT_TREE  treehead ,symbol ,flags ,user-compare-routine

                       ,user-allocation-procedure ,new-node

                       [,user-data]

1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (signed)
    access:       write only
    mechanism:    by value

2  –  Arguments

 treehead

    OpenVMS usage:address
    type:         address
    access:       modify
    mechanism:    by reference

    Tree head for the binary tree. The treehead argument is the
    address of a longword that is this tree head. The initial value
    of treehead is 0.

 symbol

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       unspecified
    mechanism:    unspecified

    Key to be inserted.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Control flags. The flags argument is the address of the control
    flags. Currently only bit 0 is used.

    Bit  Action if Set    Action if Clear

    0    Duplicate        The address of the existing duplicate entry
         entries are      is returned to the new-node argument.
         inserted.

 user-compare-routine

    OpenVMS usage:procedure
    type:         procedure value
    access:       function call (before return)
    mechanism:    by value

    User-supplied compare routine that LIB$INSERT_TREE calls to
    compare a symbol with a node. The user-compare-routine argument
    is required; LIB$INSERT_TREE calls the compare routine for every
    node except the first node in the tree. The value returned by the
    compare routine indicates the relationship between the symbol key
    and the node.

 user-allocation-procedure

    OpenVMS usage:procedure
    type:         procedure value
    access:       function call (before return)
    mechanism:    by value

    User-supplied allocate routine that LIB$INSERT_TREE calls to
    allocate virtual memory for a node. The user-allocation-procedure
    argument is required; LIB$INSERT_TREE always calls the allocate
    routine.

 new-node

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Location where the new key is inserted. The new-node argument is
    the address of an unsigned longword that is the address of the
    new node.

 user-data

    OpenVMS usage:user_arg
    type:         unspecified
    access:       unspecified
    mechanism:    by value

    User data that LIB$INSERT_TREE passes to the compare and allocate
    routines. The user-data argument is optional.