---

4.7 Java Legacy API

This API has identical argument configurations as the C code, including length arguments to complement each byte-vector argument.

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 btGet (Han han, byte []keyStr, int kLen, byte []ansStr) ¶

keyStr is a string of length kLen. btGet stores into the string ansStr the value associated with keyStr in tree han. btGet returns the length of the string stored into ansStr or an error code.

Function: int btNext (Han han, byte []keyStr, int kLen, byte []ansStr) ¶

keyStr is a string of length kLen. btNext stores into the string ansStr the next key after keyStr in tree han. btNext returns the length of the string stored into ansStr or an error code.

Function: int btPrev (Han han, byte []keyStr, int kLen, byte []ansStr) ¶

keyStr is a string of length kLen. btPrev stores into the string ansStr the last key before keyStr in tree han. btPrev returns the length of the string stored into ansStr or an error code.

Function: int btRem (Han han, byte []keyStr, int kLen, byte []ansStr) ¶

keyStr is a string of length kLen. btRem stores into the string ansStr the value associated with keyStr in tree han; then removes that association from tree han. btRem returns the length of the string stored into ansStr or an error code.

If ansStr is 0, btRem removes the keyStr association from tree han and returns SUCCESS if successful; an error code if not.

Function: int btRemRange (Han han, byte []keyStr, int kLen, byte []key2Str, int k2Len) ¶

keyStr must be a maximum-length (256 byte) string containing a key kLen bytes long. key2Str is a string of length k2Len.

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

Function: int btPut (Han han, byte []keyStr, int kLen, byte []valStr, int vLen) ¶

keyStr is a string of length kLen. valStr is a string of length vLen. btPut makes the value associated with keyStr be valStr in tree han. btPut returns a status code for the operation.

Function: int btWrite (Han han, byte []keyStr, int kLen, byte []valStr, int vLen) ¶

keyStr is a string of length kLen. valStr is a string of length vLen. If han currently contains an association for keyStr, then btWrite does not modify the tree and returns the notpres status code.

Otherwise, btWrite makes the value associated with keyStr be valStr in tree han. btWrite returns a status code for the operation.

Function: int btScan (Han han, int operation, byte []kstr1, int len1, byte []kstr2, int len2, java.lang.reflect.Method func, int []longTab, int []respkt, 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 SUCCESS if scan completed; under any other result code the scan is resumable. The possible results are:

NOTPRES

meaning the blkLimit was exceeded;

RETRYERR

meaning func or delete got a RETRYERRR;

TERMINATED

meaning func asked to terminate the scan;

<other error>

means func or DELETE encountered this errror.

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.

The number of keys deleted/counted/modified is returned in the skey-count field of respkt; the key to resume at is returned in kstr1 (which therefore needs to be 256 bytes long); and the new key length is returned in the skey-len field of respkt. If returns SUCCESS, skey-len is zero. NOTE that skey-count is cumulative, so the caller needs to initialize it to 0 when starting a new btScan.

WARNING: when btScan returns other than SUCCESS, it modifies the kstr1 string so that the string args are correctly set up for the next call (the returned value is the new length for kstr1). Therefore, kstr1 must be a maximum-length string!