m4_comment([$Id: dbc_put.so,v 11.18 2004/12/02 18:21:08 bostic Exp $])

define(M4PAGELOCAL,)
include(tcl/m4.tcl)

m4_tcl_header(dbc put, m4_tcl_dbc_put, [dnl
dbc put
	m4_tcl_arg([-after])
	m4_tcl_arg([-before])
	m4_tcl_arg([-current])
	m4_tcl_arg([-partial {doff dlen}])
	data
dbc put
	m4_tcl_arg([-keyfirst])
	m4_tcl_arg([-keylast])
	m4_tcl_arg([-partial {doff dlen}])
	key data
])

m4_p([dnl
The m4_tcl_dbc_put command stores the specified key/data pair into the
database.  One of the following options must be specified:])

m4_tagbegin

m4_tag([-after], [dnl
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 m4_arg(-after) if the underlying Btree or Hash database
was not created with the m4_arg(-dup) option. No key argument should be
specified.
m4_p([dnl
In the case of the Recno access method, it is an error to specify the
m4_arg(-after) option if the underlying Recno database was not created
with the m4_arg(-renumber) option.  If the m4_arg(-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 m4_tcl_db_open for more information.])
m4_p([dnl
In the case of the Queue access method, it is always an error to specify
m4_arg(-after).])
m4_p([dnl
If the current cursor record has already been deleted, and the underlying
access method is Hash, m4_tcl_dbc_put will throw a Tcl error. If the
underlying access method is Btree or Recno, the operation will succeed.])])

m4_tag([-before], [dnl
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 m4_arg(-before) if the underlying Btree or Hash database
was not created with the m4_arg(-dup) option. No key argument should be
specified.
m4_p([dnl
In the case of the Recno access method, it is an error to specify
m4_arg(-before) if the underlying Recno database was not created with the
m4_arg(-before) option.  If the m4_arg(-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 m4_tcl_db_open for more information.])
m4_p([dnl
In the case of the Queue access method, it is always an error to specify
m4_arg(-before).])
m4_p([dnl
If the current cursor record has already been deleted and the underlying
access method is Hash, m4_tcl_dbc_put will throw a Tcl error. If the
underlying access method is Btree or Recno, the operation will succeed.])])

m4_tag([-current], [dnl
Overwrite the data of the key/data pair to which the cursor refers with
the specified data item.  No key argument should be specified.
m4_p([dnl
If the m4_arg(-dupsort) option was specified to m4_tcl_db_open and the
data item of the key/data pair to which the cursor refers does not
compare equally to the data parameter, m4_tcl_dbc_put will throw a Tcl
error.])
m4_p([dnl
If the current cursor record has already been deleted and the underlying
access method is Hash, m4_tcl_dbc_put will throw a Tcl error. If the
underlying access method is Btree, Queue, or Recno, the operation will
succeed.])])

m4_tag([-keyfirst], [dnl
In the case of the Btree and Hash access methods, insert the specified
key/data pair into the database.
m4_p([dnl
If the key already exists in the database, and the m4_arg(-dupsort) option
was specified to m4_tcl_db_open, the inserted data item is added in its
sorted location.  If the key already exists in the database, and the
m4_arg(-dupsort) option was not specified, the inserted data item is added
as the first of the data items for that key.])
m4_p([dnl
The m4_arg(-keyfirst) option may not be specified to the Queue or Recno
access methods.])])

m4_tag([-keylast], [dnl
In the case of the Btree and Hash access methods, insert the specified
key/data pair into the database.
m4_p([dnl
If the key already exists in the database, and the m4_arg(-dupsort) option
was specified to m4_tcl_db_open, the inserted data item is added in its
sorted location.  If the key already exists in the database, and the
m4_arg(-dupsort) option was not specified, the inserted data item is added
as the last of the data items for that key.])
m4_p([dnl
The m4_arg(-keylast) option may not be specified to the Queue or Recno
access methods.])])

m4_tag([-partial {doff dlen}], [m4_tcl_partial_put(m4_tcl_dbc_put)])

m4_tagend

m4_p([dnl
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.])

m4_p([dnl
If m4_tcl_dbc_put fails for any reason, the state of the cursor will be
unchanged. If m4_tcl_dbc_put succeeds and an item is inserted into the
database, the cursor is always positioned to refer to the newly inserted
item.])

m4_tcl_ret_standard(m4_tcl_dbc_put)

m4_page_footer