---

3.4 C HANDs and Tree Operations

Function: void close_bt (HAND * han) ¶

Closes and frees han; the b-tree associated with han remains in the segment.

For create-db and open-db, the implicit WCB argument is the combination of ‘WCB-SAP’ and ‘WCB-SAR’.

Function: HAND * create_db (SEGD * seg, int typ, unsigned char * name_str) ¶

Returns a B-tree whose name has been entered in the root directory if successful; otherwise null.

typ should be either

• 'D' (directory) or
• 'T' (regular tree).

B-trees with typ #\D which are pointed to by special entries in the root block (1) protect all their special entries from garbage collection by the wbcheck program. 'T' is for regular (data) arrays.

Function: HAND * open_db (SEGD * seg, unsigned char * name_str) ¶

Returns the B-tree whose name has been entered in the root directory; or null if not found.

Function: int flush_ents (int attempts, int k) ¶

k is the number of dirty block buffers to write to disk; attempts is the number of times to try. Note that blocks in any segment may be written by flush-ents. flush-ents returns the number of blocks written.

Note: most of the data-manipulating commands here can return notpres, with the followng meanings:

bt-get	key was not found.
bt-next	no next key (eg, given key was last key).
bt-prev	no prev key (eg, given key was first key).
bt-rem	key was not found.
bt-put	unused (could be symmetric with write).
bt-write	key was found, so no write was done.

Function: int bt_get (HAND * han, unsigned char * key_str, int k_len, unsigned char * ans_str) ¶

key_str is a string of length k_len. bt_get stores into the string ans_str the value associated with key_str in tree han. bt_get returns the length of the string stored into ans_str or an error code.

Function: int bt_next (HAND * han, unsigned char * key_str, int k_len, unsigned char * ans_str) ¶

key_str is a string of length k_len. bt_next stores into the string ans_str the next key after key_str in tree han. bt_next returns the length of the string stored into ans_str or an error code.

Function: int bt_prev (HAND * han, unsigned char * key_str, int k_len, unsigned char * ans_str) ¶

key_str is a string of length k_len. bt_prev stores into the string ans_str the last key before key_str in tree han. bt_prev returns the length of the string stored into ans_str or an error code.

Function: int bt_rem (HAND * han, unsigned char * key_str, int k_len, unsigned char * ans_str) ¶

key_str is a string of length k_len. bt_rem stores into the string ans_str the value associated with key_str in tree han; then removes that association from tree han. bt_rem returns the length of the string stored into ans_str or an error code.

If ans_str is 0, bt_rem removes the key_str association from tree han and returns SUCCESS if successful; an error code if not.

Function: int bt_rem_range (HAND * han, unsigned char * key_str, int k_len, unsigned char * key2_str, int k2_len) ¶

key_str must be a maximum-length (256 byte) string containing a key k_len bytes long. key2_str is a string of length k2_len.

bt_rem_range removes [key_str … key2_str) and their values. If key2_str <= key_str no deletion will occur (even if key_str is found). bt_rem_range returns SUCCESS if the operation is complete, an error status code if not.

Function: int bt_put (HAND * han, unsigned char * key_str, int k_len, unsigned char * val_str, int v_len) ¶

key_str is a string of length k_len. val_str is a string of length v_len. bt_put makes the value associated with key_str be val_str in tree han. bt_put returns a status code for the operation.

Function: int bt_write (HAND * han, unsigned char * key_str, int k_len, unsigned char * val_str, int v_len) ¶

key_str is a string of length k_len. val_str is a string of length v_len. If han currently contains an association for key_str, then bt_write does not modify the tree and returns the notpres status code.

Otherwise, bt_write makes the value associated with key_str be val_str in tree han. bt_write returns a status code for the operation.