```{index} single: seq (DB_File) ``` ```{index} single: DB_File::seq ``` # seq Move the database's cursor and read the key and value it lands on: walk the database in order, or find the first key at or after a given one. ## Synopsis ```perl my ($key, $value) = ('', ''); my $status = $db->seq($key, $value, R_FIRST); ``` ## What you get back 0 with `$key` and `$value` set to where the cursor landed, 1 when there is nothing there (past either end, or no such key), -1 for an error. On 1 the cursor stays where it was. For an array, `$key` is an index. ## Flags - `R_FIRST`, `R_LAST` - the first or last key. - `R_NEXT`, `R_PREV` - the key after or before the cursor; from no cursor yet, the first or the last. - `R_CURSOR` - in a `$DB_BTREE` database the first key at or after `$key`; in a `$DB_HASH` database `$key` itself; in an array element `$key`. ## Examples Walk a database in order: ```perl my ($k, $v) = ('', ''); for (my $st = $db->seq($k, $v, R_FIRST); $st == 0; $st = $db->seq($k, $v, R_NEXT)) { print "$k=$v\n"; } ``` Find the first key starting with `Wa` in a `$DB_BTREE` database: ```perl @h{qw(Smith Wall Walls)} = (1, 2, 3); my ($k, $v) = ('Wa', ''); print "$k\n" if $db->seq($k, $v, R_CURSOR) == 0 and $k =~ /^Wa/; # Wall ``` ## Edge cases - `$key` and `$value` must be variables: the method writes them. - Array elements created empty are passed over; `R_CURSOR` on one returns `-30995` (Berkeley DB's `DB_KEYEMPTY`). - In an `R_DUP` database `R_NEXT` and `R_PREV` step through a key's values one by one, in the order they were stored. - The tie interface (`keys`, `each`) moves the same cursor. ## Differences from upstream Fully compatible with upstream. Covered by `t/81-xs-native/DB_File/010-phenotype.t`. ## See also - `get` - looks up one key without moving the cursor - `del` and `put` - act at the cursor with `R_CURSOR` - `get_dup` - all the values of a key