---

3.5 C Scan

Function: int bt_scan (HAND * han, int operation, unsigned char * kstr1, int len1, unsigned char * kstr2, int len2, int_function func, long * long_tab, int * respkt, int blk_limit) ¶

bt_scan 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

bt_scan returns SUCCESS if scan completed; under any other result code the scan is resumable. The possible results are:

NOTPRES

meaning the blk_limit 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 bt_scan will 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 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 bt_scan.

WARNING: when 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!