1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
4
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
5
<META NAME="GENERATOR" CONTENT="Mozilla/4.08 [en] (X11; I; FreeBSD 3.3-RELEASE i386) [Netscape]">
10
<A NAME="Database Commands"></A>Database Commands</H2>
11
The database commands provide a conduit into the DB method functions.
12
They are all fairly straightforward and I describe them in terms of their
13
DB functions briefly here, with a link to the DB page where appropriate.
14
The first set of commands are those I believe will be the primary functions
15
used by most databases. Some are directly related to their DB counterparts,
16
and some are higher level functions that are useful to provide the user.
17
<P><B>> berkdb open [-env <I>env</I>]</B>
18
<BR><B> [-btree|-hash|-recno|-queue|-unknown]</B>
19
<BR><B> [-create] [-excl] [-nommap] [-rdonly] [-truncate]
21
<I>mode</I>] [-errfile <I>filename</I>]</B>
22
<BR><B> [-dup] [-dupsort] [-recnum] [-renumber] [-revsplitoff]
24
<BR><B> [-btcompare <I>proc</I>] [-dupcompare <I>proc</I>]
25
[-hashproc <I>proc</I>]</B>
26
<BR><B> [-extent <I>size</I>]</B>
27
<BR><B> [-ffactor <I>density</I>]</B>
28
<BR><B> [-nelem <I>size</I>]</B>
29
<BR><B> [-lorder <I>order</I>]</B>
30
<BR><B> [-delim <I>delim</I>]</B>
31
<BR><B> [-len <I>len</I>]</B>
32
<BR><B> [-pad <I>pad</I>]</B>
33
<BR><B> [-source <I>file</I>]</B>
34
<BR><B> [-minkey <I>minkey</I>]</B>
35
<BR><B> [-cachesize {<I>gbytes bytes ncaches</I>}]</B>
36
<BR><B> [-pagesize <I>pagesize</I>]</B>
37
<BR><B> [--]</B>
38
<BR><B> [<I>filename </I>[<I>subdbname</I>]]</B>
39
<P>This command will invoke the <A HREF="../../docs/api_c/db_create.html">db_create</A>
40
function. If the command is given the <B>-env</B> option, then we
41
will accordingly creating the database within the context of that environment.
42
After it successfully gets a handle to a database, we bind it to a new
43
Tcl command of the form <B><I>dbX, </I></B>where X is an integer starting
44
at 0 (e.g. <B>db0, db1, </B>etc). We use the <I>Tcl_CreateObjCommand() </I>
45
to create the top level database function. It is through this handle
46
that the user can access all of the commands described in the <A HREF="#Database Commands">Database
47
Commands</A> section. Internally, the database handle is sent as
48
the <I>ClientData</I> portion of the new command set so that all future
49
database calls access the appropriate handle.
50
<P>After parsing all of the optional arguments affecting the setup of the
51
database and making the appropriate calls to DB to manipulate those values,
52
we open the database for the user. It translates to the
53
<A HREF="../../docs/api_c/db_open.html">DB->open</A>
54
method call after parsing all of the various optional arguments.
55
We automatically set the DB_THREAD flag. The arguments are:
58
<B>-- </B>- Terminate the list of options and use remaining arguments as
59
the file or subdb names (thus allowing the use of filenames beginning with
63
<B>-btree</B> - DB_BTREE database</LI>
66
<B>-hash</B> - DB_HASH database</LI>
69
<B>-recno </B> - DB_RECNO database</LI>
72
<B>-queue</B> - DB_QUEUE database</LI>
75
<B>-create</B> selects the DB_CREATE flag to create underlying files</LI>
78
<B>-excl</B> selects the DB_EXCL flag to exclusively create underlying
82
<B>-nommap</B> selects the DB_NOMMAP flag to forbid mmaping of files</LI>
85
<B>-rdonly</B> selects the DB_RDONLY flag for opening in read-only mode</LI>
88
<B>-truncate</B> selects the DB_TRUNCATE flag to truncate the database</LI>
91
<B>-mode<I> mode</I></B> specifies the mode for created files</LI>
94
<B>-errfile </B>specifies the error file to use for this environment to
95
<B><I>filename</I></B>
96
by calling <A HREF="../../docs/api_c/db_set_errfile.html">DB->set_errfile</A><B><I>.
98
the file already exists then we will append to the end of the file</LI>
101
<B>-dup </B>selects the DB_DUP flag to permit duplicates in the database</LI>
104
<B>-dupsort</B> selects the DB_DUPSORT flag to support sorted duplicates</LI>
107
<B>-recnum</B> selects the DB_RECNUM flag to support record numbers in
111
<B>-renumber </B>selects the DB_RENUMBER flag to support mutable record
115
<B>-revsplitoff </B>selects the DB_REVSPLITOFF flag to suppress reverse
116
splitting of pages on deletion</LI>
119
<B>-snapshot </B>selects the DB_SNAPSHOT flag to support database snapshots</LI>
122
<B>-btcompare</B> sets the Btree comparison function to the Tcl procedure
123
named <B><I>proc</I></B> using the <A HREF="../../docs/api_c/db_set_bt_compare.html">DB->set_bt_compare</A>
127
<B>-dupcompare</B> sets the duplicate data comparison function to the Tcl
128
procedure named <B><I>proc</I></B> using the <A HREF="../../docs/api_c/db_set_dup_compare.html">DB->set_dup_compare</A>
132
<B>-hashproc</B> sets a user-defined hash function to the Tcl procedure
133
named <B><I>proc</I></B> using the <A HREF="../../docs/api_c/db_set_h_hash.html">DB->set_h_hash</A>
137
<B>-extent </B>sets the size of a Queue database extent to the given <B><I>size
139
the <A HREF="../../docs/api_c/db_set_q_extentsize.html">DB->set_q_extentsize</A>
143
<B>-ffactor</B> sets the hash table key density to the given <B><I>density
145
the <A HREF="../../docs/api_c/db_set_h_ffactor.html">DB->set_h_ffactor</A>
149
<B>-nelem </B>sets the hash table size estimate to the given <B><I>size
151
the <A HREF="../../docs/api_c/db_set_h_nelem.html">DB->set_h_nelem</A>
155
<B>-lorder </B>sets the byte order for integers stored in the database
156
meta-data to the given <B><I>order</I></B> using the <A HREF="../../docs/api_c/db_set_lorder.html">DB->set_lorder</A>
160
<B>-delim </B>sets the delimiting byte for variable length records to
162
using the <A HREF="../../docs/api_c/db_set_re_delim.html">DB->set_re_delim</A>
166
<B>-len </B>sets the length of fixed-length records to <B><I>len</I></B>
167
using the <A HREF="../../docs/api_c/db_set_re_len.html">DB->set_re_len</A>
171
<B>-pad </B>sets the pad character used for fixed length records to
172
<B><I>pad</I></B>
173
using the <A HREF="../../docs/db_set_re_pad.html">DB->set_re_pad</A> method</LI>
176
<B>-source </B>sets the backing source file name to <B><I>file</I></B>
177
using the <A HREF="../../docs/api_c/db_set_re_source.html">DB->set_re_source</A>
181
<B>-minkey </B>sets the minimum number of keys per Btree page to <B><I>minkey</I></B>
182
using the <A HREF="../../docs/api_c/db_set_bt_minkey.html">DB->set_bt_minkey</A>
186
<B>-cachesize </B>sets the size of the database cache to the size
187
specified by <B><I>gbytes </I></B>and <B><I>bytes, </I></B>broken up into
188
<B><I>ncaches</I></B>
189
number of caches using the <A HREF="../../docs/api_c/db_set_cachesize.html">DB->set_cachesize</A>
193
<B>-pagesize </B>sets the size of the database page to <B><I>pagesize </I></B>using
194
the <A HREF="../../docs/api_c/db_set_pagesize.html">DB->set_pagesize</A>
198
<B><I>filename</I></B> indicates the name of the database</LI>
201
<B><I>subdbname</I></B> indicate the name of the sub-database</LI>
205
<BR><B> berkdb upgrade [-dupsort] [-env <I>env</I>] [--] [<I>filename</I>]</B>
206
<P>This command will invoke the <A HREF="../../docs/api_c/db_upgrade.html">DB->upgrade</A>
207
function. If the command is given the <B>-env</B> option, then we
208
will accordingly upgrade the database filename within the context of that
209
environment. The <B>-dupsort</B> option selects the DB_DUPSORT flag for
210
upgrading. The use of --<B> </B>terminates the list of options, thus allowing
211
filenames beginning with a dash.
213
<HR WIDTH="100%"><B>> berkdb verify [-env <I>env</I>] [--] [<I>filename</I>]</B>
214
<P>This command will invoke the <A HREF="../../docs/api_c/db_verify.html">DB->verify</A>
215
function. If the command is given the <B>-env</B> option, then we
216
will accordingly verify the database filename within the context of that
217
environment. The use of --<B> </B>terminates the list of options,
218
thus allowing filenames beginning with a dash.
220
<HR WIDTH="100%"><B>> <I>db</I> join [-nosort] <I>db0.c0 db1.c0</I> ...</B>
221
<P>This command will invoke the <A HREF="../../docs/api_c/db_join.html">db_join</A>
222
function. After it successfully joins a database, we bind it to a
223
new Tcl command of the form <B><I>dbN.cX, </I></B>where X is an integer
224
starting at 0 (e.g. <B>db2.c0, db3.c0, </B>etc). We use the <I>Tcl_CreateObjCommand() </I>
225
to create the top level database function. It is through this cursor
226
handle that the user can access the joined data items.
230
<B>-nosort -</B> This flag causes DB not to sort the cursors based on the
231
number of data items they reference. It results in the DB_JOIN_NOSORT
235
<HR WIDTH="100%"><B>> <I>db</I> get_join [-nosort] {db key} {db key} ...</B>
236
<P>This command performs a join operation on the keys specified and returns
237
a list of the joined {key data} pairs.
241
<B>-nosort</B> This flag causes DB not to sort the cursors based on the
242
number of data items they reference. It results in the DB_JOIN_NOSORT
246
<HR WIDTH="100%"><B>> <I>db</I> keyrange [-txn <I>id</I>] key</B>
247
<P>This command returns the range for the given <B>key</B>. It returns
248
a list of 3 double elements of the form {<B><I>less equal greater</I></B>}
249
where <B><I>less</I></B> is the percentage of keys less than the given
250
key, <B><I>equal</I></B> is the percentage equal to the given key and <B><I>greater</I></B>
251
is the percentage greater than the given key. If the -txn option
252
is specified it performs this operation under transaction protection.
254
<HR WIDTH="100%"><B>> <I>db</I> put</B>
255
<P>The <B>undocumented</B> options are:
258
<B>-nodupdata</B> This flag causes DB not to insert the key/data pair if
259
it already exists, that is, both the key and data items are already in
260
the database. The -nodupdata flag may only be specified if the underlying
261
database has been configured to support sorted duplicates.</LI>
264
<HR WIDTH="100%"><B>> <I>dbc</I> put</B>
265
<P>The <B>undocumented</B> options are:
268
<B>-nodupdata</B> This flag causes DB not to insert the key/data pair if
269
it already exists, that is, both the key and data items are already in
270
the database. The -nodupdata flag may only be specified if the underlying
271
database has been configured to support sorted duplicates.</LI>
added
removed
db/tcl/docs/db.html
