dbc get |
dbc get [-consume] [-current] [-first] [-get_recno] [-join_item] [-last] [-next] [-nextdup] [-nextnodup] [-partial {offset length}] [-prev] [-prevnodup] [-rmw] dbc get [-partial {offset length}] [-rmw] [-set] [-set_range] [-set_recno] key dbc get -get_both [-partial {offset length}] [-rmw] key data
The dbc get command returns a list of {key value} pairs, except in the case of the -get_recno and -join_item options. In the case of the -get_recno option, dbc get returns a list of the record number. In the case of the -join_item option, dbc get returns a list containing the joined key.
The options are as follows:
A record is available if it is not deleted and is not currently locked. For the -consume option to be specified, the underlying database must be of type Queue.
If the cursor key/data pair was deleted, dbc get will return an empty list.
If the database is a Queue or Recno database, dbc get using the -first option will skip any keys that exist but were never explicitly created by the application or were created and later deleted.
If the database is empty, dbc get will return an empty list.
If the database is a Queue or Recno database, dbc get using the -last option will skip any keys that exist but were never explicitly created by the application or were created and later deleted.
If the database is empty, dbc get will return an empty list.
Otherwise, the cursor is moved to the next key/data pair of the database, and that pair is returned. In the presence of duplicate key values, the value of the key may not change.
If the database is a Queue or Recno database, dbc get using the -next option will skip any keys that exist but were never explicitly created by the application or were created and later deleted.
If the cursor is already on the last record in the database, dbc get will return an empty list.
Otherwise, the cursor is moved to the next non-duplicate key/data pair of the database, and that pair is returned.
If no non-duplicate key/data pairs occur after the cursor position in the database, dbc get will return an empty list.
Otherwise, the cursor is moved to the previous key/data pair of the database, and that pair is returned. In the presence of duplicate key values, the value of the key may not change.
If the database is a Queue or Recno database, dbc get using the -prev flag will skip any keys that exist but were never explicitly created by the application or were created and later deleted.
If the cursor is already on the first record in the database, dbc get will return an empty list.
Otherwise, the cursor is moved to the previous non-duplicate key/data pair of the database, and that pair is returned.
If no non-duplicate key/data pairs occur before the cursor position in the database, dbc get will return an empty list.
In the presence of duplicate key values, dbc get will return the first data item for the given key.
If the database is a Queue or Recno database and the requested key exists, but was never explicitly created by the application or was later deleted, dbc get will return an empty list.
If no matching keys are found, dbc get will return an empty list.
For -get_both to be specified, the underlying database must be of type Btree or Hash.
For the -set_recno option to be specified, the underlying database must be of type Btree and it must have been created with the -recnum option.
For -get_recno to be specified, the underlying database must be of type Btree and it must have been created with the -recnum option.
For -join_item to be specified, the cursor must have been created by the db join command.
In the normal error case of attempting to retrieve a key that does not exist an empty list is returned.
In the case of error, a Tcl error is thrown.