# db put |

`

###

    db put
    	-append
    	[-auto_commit]
    	[-partial {doff dlen}]
    	[-txn txnid]
    	data
    db put
    	[-auto_commit]
    	[-nooverwrite]
    	[-partial {doff dlen}]
    	[-txn txnid]
    	key data

# Description

The db put command stores the specified key/data pair into the database.

The options are as follows:

-auto_commit
  Enclose the call within a transaction. If the call succeeds, changes made by the operation will be recoverable. If the call fails, the operation will have made no changes.

-append
  Append the data item to the end of the database. For the -append option to be specified, the underlying database must be a Queue or Recno database. The record number allocated to the record is returned on success.

-nooverwrite
  Enter the new key/data pair only if the key does not already appear in the database.

-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 db put call will succeed.

  It is an error to attempt a partial put using the db 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.

-txn txnid
  If the operation is to be transaction-protected (other than by specifying the -auto_commit flag), the txnid parameter is a transaction handle returned from env txn.

The db put command returns either 0 or a record number for success (the record number is returned if the -append option was specified). If an error occurs, a Berkeley DB error message is returned or a Tcl error is thrown.

If the underlying database is a Queue or Recno database, then 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.

`

Copyright Sleepycat Software