lang/tcl/docs/db.html

   1 <!--Copyright (c) 1999, 2012 Oracle and/or its affiliates.  All rights reserved.-->
   2 <HTML>
   3 <HEAD>
   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]">
   6 </HEAD>
   7 <BODY>
   8
   9 <H2>
  10 <A NAME="Database Commands"></A>Database Commands</H2>
  11 The database commands provide a fairly straightforward mapping to the
  12 DB method functions.
  13
  14 <P>
  15 <B>> berkdb open</B>
  16 <dl>
  17
  18 <dt><B>[-btcompare <I>proc</I>]</B><dd>
  19 Sets the Btree comparison function to the Tcl procedure named
  20 <I>proc</I> using the
  21 <A HREF="../../docs/api_c/db_set_bt_compare.html">DB->set_bt_compare</A>
  22 method.
  23
  24 <dt><B>[-btree|-hash|-recno|-queue|-unknown]</B><dd>
  25 </td><td>
  26 Select the database type:<br>
  27 DB_BTREE, DB_HASH, DB_RECNO, DB_QUEUE or DB_UNKNOWN.
  28
  29
  30 <dt><B>[-cachesize {<I>gbytes bytes ncaches</I>}]</B><dd>
  31 Sets the size of the database cache to the size specified by
  32 <I>gbytes</I> and <I>bytes</I>, broken up into <I>ncaches</I> number of
  33 caches using the
  34 <A HREF="../../docs/api_c/db_set_cachesize.html">DB->set_cachesize</A>
  35 method.
  36
  37 <dt><B>[-create]</B><dd>
  38 Selects the DB_CREATE flag to create underlying files.
  39
  40 <dt><B>[-delim <I>delim</I>]</B><dd>
  41 Sets the delimiting byte for variable length records to <I>delim</I>
  42 using the
  43 <A HREF="../../docs/api_c/db_set_re_delim.html">DB->set_re_delim</A>
  44 method.
  45
  46 <dt><B>[-compress]</B><dd>
  47 Enables default compression using the
  48 <A HREF="../../docs/api_c/db_set_bt_compress.html">DB->set_bt_compress</A>
  49 method.
  50
  51 <dt><B>[-dup]</B><dd>
  52 Selects the DB_DUP flag to permit duplicates in the database.
  53
  54 <dt><B>[-dupcompare <I>proc</I>]</B><dd>
  55 Sets the duplicate data comparison function to the Tcl procedure named
  56 <I>proc</I> using the
  57 <A HREF="../../docs/api_c/db_set_dup_compare.html">DB->set_dup_compare</A>
  58 method.
  59
  60 <dt><B>[-dupsort]</B><dd>
  61 Selects the DB_DUPSORT flag to support sorted duplicates.
  62
  63 <dt><B>[-env <I>env</I>]</B><dd>
  64 The database environment.
  65
  66 <dt><B>[-errfile <I>filename</I>]</B><dd>
  67 Specifies the error file to use for this environment to <I>filename</I>
  68 by calling
  69 <A HREF="../../docs/api_c/db_set_errfile.html">DB->set_errfile</A>.
  70 If the file already exists then we will append to the end of the file.
  71
  72 <dt><B>[-excl]</B><dd>
  73 Selects the DB_EXCL flag to exclusively create underlying files.
  74
  75 <dt><B>[-extent <I>size</I>]</B><dd>
  76 Sets the size of a Queue database extent to the given <I>size</I> using
  77 the
  78 <A HREF="../../docs/api_c/db_set_q_extentsize.html">DB->set_q_extentsize</A>
  79 method.
  80
  81 <dt><B>[-ffactor <I>density</I>]</B><dd>
  82 Sets the hash table key density to the given <I>density</I> using the
  83 <A HREF="../../docs/api_c/db_set_h_ffactor.html">DB->set_h_ffactor</A>
  84 method.
  85
  86 <dt><B>[-hashproc <I>proc</I>]</B><dd>
  87 Sets a user-defined hash function to the Tcl procedure named <I>proc</I>
  88 using the
  89 <A HREF="../../docs/api_c/db_set_h_hash.html">DB->set_h_hash</A> method.
  90
  91 <dt><B>[-len <I>len</I>]</B><dd>
  92 Sets the length of fixed-length records to <I>len</I> using the
  93 <A HREF="../../docs/api_c/db_set_re_len.html">DB->set_re_len</A>
  94 method.
  95
  96 <dt><B>[-lorder <I>order</I>]</B><dd>
  97 Sets the byte order for integers stored in the database meta-data to
  98 the given <I>order</I> using the
  99 <A HREF="../../docs/api_c/db_set_lorder.html">DB->set_lorder</A>
 100 method.
 101
 102 <dt><B>[-minkey <I>minkey</I>]</B><dd>
 103 Sets the minimum number of keys per Btree page to <I>minkey</I> using
 104 the
 105 <A HREF="../../docs/api_c/db_set_bt_minkey.html">DB->set_bt_minkey</A>
 106 method.
 107
 108 <dt><B>[-mode <I>mode</I>]</B><dd>
 109 Specifies the mode for created files.
 110
 111 <dt><B>[-nelem <I>size</I>]</B><dd>
 112 Sets the hash table size estimate to the given <I>size</I> using the
 113 <A HREF="../../docs/api_c/db_set_h_nelem.html">DB->set_h_nelem</A>
 114 method.
 115
 116 <dt><B>[-nommap]</B><dd>
 117 Selects the DB_NOMMAP flag to forbid mmaping of files.
 118
 119 <dt><B>[-pad <I>pad</I>]</B><dd>
 120 Sets the pad character used for fixed length records to <I>pad</I> using
 121 the
 122 <A HREF="../../docs/db_set_re_pad.html">DB->set_re_pad</A> method.
 123
 124 <dt><B>[-pagesize <I>pagesize</I>]</B><dd>
 125 Sets the size of the database page to <I>pagesize</I> using the
 126 <A HREF="../../docs/api_c/db_set_pagesize.html">DB->set_pagesize</A>
 127 method.
 128
 129 <dt><B>[-rdonly]</B><dd>
 130 Selects the DB_RDONLY flag for opening in read-only mode.
 131
 132 <dt><B>[-recnum]</B><dd>
 133 Selects the DB_RECNUM flag to support record numbers in Btrees.
 134
 135 <dt><B>[-renumber]</B><dd>
 136 Selects the DB_RENUMBER flag to support mutable record numbers.
 137
 138 <dt><B>[-revsplitoff]</B><dd>
 139 Selects the DB_REVSPLITOFF flag to suppress reverse splitting of pages
 140 on deletion.
 141
 142 <dt><B>[-snapshot]</B><dd>
 143 Selects the DB_SNAPSHOT flag to support database snapshots.
 144
 145 <dt><B>[-source <I>file</I>]</B><dd>
 146 Sets the backing source file name to <I>file</I> using the
 147 <A HREF="../../docs/api_c/db_set_re_source.html">DB->set_re_source</A>
 148 method.
 149
 150 <dt><B>[-truncate]</B><dd>
 151 Selects the DB_TRUNCATE flag to truncate the database.
 152
 153 <dt><B>[--]</B><dd>
 154 Terminate the list of options and use remaining arguments as the file
 155 or subdb names (thus allowing the use of filenames beginning with a dash
 156 '-').
 157
 158 <dt><B>[<I>filename </I>[<I>subdbname</I>]]</B><dd>
 159 The names of the database and sub-database.
 160 </dl>
 161
 162 <HR WIDTH="100%">
 163 <B>> berkdb upgrade [-dupsort] [-env <I>env</I>] [--] [<I>filename</I>]</B>
 164 <P>This command will invoke the <A HREF="../../docs/api_c/db_upgrade.html">DB->upgrade</A>
 165 function.&nbsp; If the command is given the <B>-env</B> option, then we
 166 will accordingly upgrade the database filename within the context of that
 167 environment. The <B>-dupsort</B> option selects the DB_DUPSORT flag for
 168 upgrading. The use of --<B> </B>terminates the list of options, thus allowing
 169 filenames beginning with a dash.
 170 <P>
 171
 172 <HR WIDTH="100%">
 173 <B>> berkdb verify [-env <I>env</I>] [--] [<I>filename</I>]</B>
 174 <P>This command will invoke the <A HREF="../../docs/api_c/db_verify.html">DB->verify</A>
 175 function.&nbsp; If the command is given the <B>-env</B> option, then we
 176 will accordingly verify the database filename within the context of that
 177 environment.&nbsp; The use of --<B> </B>terminates the list of options,
 178 thus allowing filenames beginning with a dash.
 179 <P>
 180
 181 <HR WIDTH="100%"><B>> <I>db</I> del</B>
 182 <P>There are no undocumented options.
 183
 184 <HR WIDTH="100%">
 185 <B>> <I>db</I> join [-nosort] <I>db0.c0 db1.c0</I> ...</B>
 186 <P>This command will invoke the <A HREF="../../docs/api_c/db_join.html">db_join</A>
 187 function.&nbsp; After it successfully joins a database, we bind it to a
 188 new Tcl command of the form <B><I>dbN.cX, </I></B>where X is an integer
 189 starting at 0 (e.g. <B>db2.c0, db3.c0, </B>etc).&nbsp; We use the <I>Tcl_CreateObjCommand()&nbsp;</I>
 190 to create the top level database function.&nbsp; It is through this cursor
 191 handle that the user can access the joined data items.
 192 <P>The options are:
 193 <UL>
 194 <LI>
 195 <B>-nosort -</B> This flag causes DB not to sort the cursors based on the
 196 number of data items they reference.&nbsp; It results in the DB_JOIN_NOSORT
 197 flag being set.</LI>
 198 </UL>
 199
 200 <P>
 201 This command will invoke the
 202 <A HREF="../../docs/api_c/db_create.html">db_create</A> function.  If
 203 the command is given the <B>-env</B> option, then we will accordingly
 204 creating the database within the context of that environment.  After it
 205 successfully gets a handle to a database, we bind it to a new Tcl
 206 command of the form <B><I>dbX, </I></B>where X is an integer starting
 207 at 0 (e.g. <B>db0, db1, </B>etc).
 208
 209 <p>
 210 We use the <I>Tcl_CreateObjCommand()</I> to create the top level
 211 database function.  It is through this handle that the user can access
 212 all of the commands described in the <A HREF="#Database Commands">
 213 Database Commands</A> section. Internally, the database handle
 214 is sent as the <I>ClientData</I> portion of the new command set so that
 215 all future database calls access the appropriate handle.
 216
 217 <P>
 218 After parsing all of the optional arguments affecting the setup of the
 219 database and making the appropriate calls to DB to manipulate those
 220 values, we open the database for the user. It translates to the
 221 <A HREF="../../docs/api_c/db_open.html">DB->open</A> method call after
 222 parsing all of the various optional arguments. We automatically set the
 223 DB_THREAD flag. The arguments are:
 224
 225 <HR WIDTH="100%">
 226 <B>> <I>db</I> get_join [-nosort] {db key} {db key} ...</B>
 227 <P>This command performs a join operation on the keys specified and returns
 228 a list of the joined {key data} pairs.
 229 <P>The options are:
 230 <UL>
 231 <LI>
 232 <B>-nosort</B> This flag causes DB not to sort the cursors based on the
 233 number of data items they reference.&nbsp; It results in the DB_JOIN_NOSORT
 234 flag being set.</LI>
 235 </UL>
 236
 237 <HR WIDTH="100%">
 238 <B>> <I>db</I> keyrange [-txn <I>id</I>] key</B>
 239 <P>This command returns the range for the given <B>key</B>.&nbsp; It returns
 240 a list of 3 double elements of the form {<B><I>less equal greater</I></B>}
 241 where <B><I>less</I></B> is the percentage of keys less than the given
 242 key, <B><I>equal</I></B> is the percentage equal to the given key and <B><I>greater</I></B>
 243 is the percentage greater than the given key.&nbsp; If the -txn option
 244 is specified it performs this operation under transaction protection.
 245
 246 <HR WIDTH="100%"><B>> <I>db</I> put</B>
 247 <P>The <B>undocumented</B> options are:
 248 <dl>
 249 <dt><B>-nodupdata</B><dd>
 250 This flag causes DB not to insert the key/data pair if it already
 251 exists, that is, both the key and data items are already in the
 252 database. The -nodupdata flag may only be specified if the underlying
 253 database has been configured to support sorted duplicates.
 254 </dl>
 255
 256 <HR WIDTH="100%"><B>> <I>dbc</I> put</B>
 257 <P>The <B>undocumented</B> options are:
 258 <dl>
 259 <dt><B>-nodupdata</B><dd>
 260 This flag causes DB not to insert the key/data pair if it already
 261 exists, that is, both the key and data items are already in the
 262 database. The -nodupdata flag may only be specified if the underlying
 263 database has been configured to support sorted duplicates.
 264 </dl>
 265
 266 </BODY>
 267 </HTML>