Next: , Previous: C SEGs, Up: C Interface


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

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.