C# HANDs and Tree Operations (wb)

5.3 C# HANDs and Tree Operations

All of the methods listed here which take byte-array arguments can also take string arguments, which get converted to UTF-8 byte-arrays.

Function: void closeBt (wb.Han han) ¶: Closes han

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

Function: Han createDb (wb.Seg seg, int typ, byte []nameStr) ¶

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: Han openDb (wb.Seg seg, byte []nameStr) ¶: Returns the B-tree whose name has been entered in the root directory; or null if not found.

Function: int flushEnts (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.

5.4 Record Operations

Function: byte []bt_Get (wb.Han han, byte []key) ¶

han is a handle to an open bt. key is a string less than 255.B in length.

bt:get returns a string of the value associated with key in the bt which han is open to. bt:get returns null if key is not associated in the bt.

Function: byte []bt_Next (wb.Han han, byte []key) ¶

han is a handle to an open bt. key is a string less than 255.B in length.

bt:next returns the next key in bt han or null if none.

Function: byte []bt_Prev (wb.Han han, byte []key) ¶

han is a handle to an open bt. key is a string less than 255.B in length.

bt:prev returns the previous key in bt han or null if none.

Function: void bt_Put (wb.Han han, byte []key, byte []valStr) ¶

han is a handle to an open, mutable bt. key and val are strings less than 255.B in length.

bt:put! associates key with val in the bt han. A status code is returned.

Function: bool bt_Del (wb.Han han, byte []key) ¶

han is a handle to an open, mutable bt. key is a string less than 255.B in length.

bt:rem! removes key and it’s associated value from bt han.

5.5 Mutual Exclusion

These 2 calls can be used for locking and synchronizing processes.

Function: bool bt_Insert (wb.Han han, byte []key, byte []valStr) ¶: Associates key with val in the bt han only if key was previously empty. Returns true for success, false for failure.

Function: byte []bt_Rem (wb.Han han, byte []key) ¶: Removes key and it’s associated value from bt han only if key is present. Returns key’s value for success, null for failure (not present).

5.6 Multiple Operations

Function: int bt_Delete (wb.Han han, byte []key, byte []key2) ¶: Removes keys (and their associated values) between (including) key1 and (not including) key2 from bt han. A status code is returned.

Function: byte []bt_Scan (wb.Han bthan, int op, byte []kstr1, byte []kstr2, string func, int blklimit) ¶

btScan scans all keys in the range [kstr1..kstr2), performing one of several functions:

`operation`	`func`	RESULT
COUNT-SCAN	NIL	counts all keys in range
COUNT-SCAN	given	counts all keys in range satisfying `func`
REM-SCAN	NIL	deletes all keys in range
REM-SCAN	given	deletes all keys in range satisfying `func`
MODIFY-SCAN	NIL	ARGERR
MODIFY-SCAN	given	updates values for keys in range satisfying `func`

btScan returns null if there was an error; an empty byte-vector if scan completed; or the next key to be scanned if blklimit was not ‘-1’.

Each block of data is scanned/deleted/modified in a single operation that is, the block is found and locked only once, and only written after all modifications are made. Tho only exception is that MODIFY-SCANs that increase the size of values can cause block splits. Such cases are detected and converted to a PUT plus a NEXT. This has two consequences: data is written out each time a PUT occurs, and it is conceivable that func may be called more than once on the key value that caused the split if a RETRYERR occurs in the PUT. However, SCAN guarantees that only one modification will actually be made in this case (so that one can write INCREMENT-RANGE, for example).

func is passed pointers to (copies of) the key and value, plus one user argument:

func (keystr, klen, vstr, vlen, extra_arg);

func is expected to return either: SUCCESS for DELETE/COUNT, NOTPRES/NOTDONE for SKIP (ie, DONT DELETE/COUNT), or any other code to terminate the scan resumably at the current point. For MODIFY-SCAN, if changing the value, the new value length is returned. Except for the case mentioned above, the caller can depend on func being called exactly once for each key value in the specified range, and only on those values.

If kstr2 <= kstr1, then no scan will occur (even if kstr1 is found). To make possible bounded-time operation btScan will access at most blkLimit blocks at a time; if you dont care, give it -1 for blkLimit.