dbc put
[-after]
[-before]
[-current]
[-partial {doff dlen}]
data
dbc put
[-keyfirst]
[-keylast]
[-partial {doff dlen}]
key data
The dbc put command stores the specified key/data pair into the database. One of the following options must be specified:
-after
In the case of the Btree and Hash access methods, insert the data element as a duplicate element of the key to which the cursor refers. The new element appears immediately after the current cursor position. It is an error to specify -after if the underlying Btree or Hash database was not created with the -dup option. No key argument should be specified.
In the case of the Recno access method, it is an error to specify the -after option if the underlying Recno database was not created with the -renumber option. If the -renumber option was specified, a new key is created, all records after the inserted item are automatically renumbered, and the key of the new record is returned in the structure to which the key argument refers. The initial value of the key parameter is ignored. See berkdb open for more information.
In the case of the Queue access method, it is always an error to specify -after.
If the current cursor record has already been deleted, and the underlying access method is Hash, dbc put will throw a Tcl error. If the underlying access method is Btree or Recno, the operation will succeed.
-before
In the case of the Btree and Hash access methods, insert the data element as a duplicate element of the key to which the cursor refers. The new element appears immediately before the current cursor position. It is an error to specify -before if the underlying Btree or Hash database was not created with the -dup option. No key argument should be specified.
In the case of the Recno access method, it is an error to specify -before if the underlying Recno database was not created with the -before option. If the -before option was specified, a new key is created, the current record and all records after it are automatically renumbered, and the key of the new record is returned in the structure to which the key argument refers. The initial value of the key parameter is ignored. See berkdb open for more information.
In the case of the Queue access method, it is always an error to specify -before.
If the current cursor record has already been deleted and the underlying access method is Hash, dbc put will throw a Tcl error. If the underlying access method is Btree or Recno, the operation will succeed.
-current
Overwrite the data of the key/data pair to which the cursor refers with the specified data item. No key argument should be specified.
If the -dupsort option was specified to berkdb open and the data item of the key/data pair to which the cursor refers does not compare equally to the data parameter, dbc put will throw a Tcl error.
If the current cursor record has already been deleted and the underlying access method is Hash, dbc put will throw a Tcl error. If the underlying access method is Btree, Queue, or Recno, the operation will succeed.
-keyfirst
In the case of the Btree and Hash access methods, insert the specified key/data pair into the database.
If the key already exists in the database, and the -dupsort option was specified to berkdb open, the inserted data item is added in its sorted location. If the key already exists in the database, and the -dupsort option was not specified, the inserted data item is added as the first of the data items for that key.
The -keyfirst option may not be specified to the Queue or Recno access methods.
-keylast
In the case of the Btree and Hash access methods, insert the specified key/data pair into the database.
If the key already exists in the database, and the -dupsort option was specified to berkdb open, the inserted data item is added in its sorted location. If the key already exists in the database, and the -dupsort option was not specified, the inserted data item is added as the last of the data items for that key.
The -keylast option may not be specified to the Queue or Recno access methods.
-partial {doff dlen}
The dlen bytes starting doff bytes from the beginning of the specified key's data record are replaced by the data specified by the data and size structure elements. If dlen is smaller than the length of the supplied data, the record will grow; if dlen is larger than the length of the supplied data, the record will shrink. If the specified bytes do not exist, the record will be extended using nul bytes as necessary, and the dbc put call will succeed.
It is an error to attempt a partial put using the dbc put command in a database that supports duplicate records. Partial puts in databases supporting duplicate records must be done using a dbc put command.
It is an error to attempt a partial put with differing dlen and supplied data length values in Queue or Recno databases with fixed-length records.
If a key is specified, and if the underlying database is a Queue or Recno database, the given key will be interpreted by Tcl as an integer. For all other database types, the key is interpreted by Tcl as a byte array.
If dbc put fails for any reason, the state of the cursor will be unchanged. If dbc put succeeds and an item is inserted into the database, the cursor is always positioned to refer to the newly inserted item.
The dbc put command returns 0 on success, and in the case of error, a Tcl error is thrown.