bt_scan scans all keys in the range [kstr1..kstr2),
performing one of several functions:
|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||given||updates values for keys in range satisfying func|
bt_scan returns 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;
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
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-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
skey-len is zero. NOTE that
skey-count is cumulative, so the caller needs to initialize
it to 0 when starting a new
bt_scan 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!