bt_scanscans 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
bt_scanreturns SUCCESS if scan completed; under any other result code the scan is resumable. The possible results are:
- meaning the blk_limit was exceeded;
- meaning func or delete got a RETRYERRR;
- 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
bt_scanwill access at most blk_limit blocks at a time; if you dont care, give it -1 for blk_limit.
The number of keys deleted/counted/modified is returned in the
skey-countfield 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-lenfield of respkt. If returns SUCCESS,
skey-lenis zero. NOTE that
skey-countis cumulative, so the caller needs to initialize it to 0 when starting a new
bt_scanreturns 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!