Previous: C# HANDs and Tree Operations, Up: C# Interface [Contents][Index]
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. |
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.
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.
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.
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.
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.
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.
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.
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:
meaning the blkLimit was exceeded;
meaning func or delete got a RETRYERRR;
meaning func asked to terminate the scan;
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!
Previous: C# HANDs and Tree Operations, Up: C# Interface [Contents][Index]