1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>db put</title> 7 <link rel="stylesheet" href="apiReference.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB TCL API Reference" /> 10 <link rel="up" href="tclapi.html" title="Chapter��1.�� Berkeley DB Tcl APIs" /> 11 <link rel="prev" href="db_open.html" title="berkdb open" /> 12 <link rel="next" href="db_remove.html" title="berkdb dbremove" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center"><span class="emphasis"><em>db</em></span> put</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="db_open.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��1.�� 23 Berkeley DB Tcl APIs 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="db_remove.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="db_put"></a><span class="emphasis"><em>db</em></span> put</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">db put 39 -append 40 [-partial {doff dlen}] 41 [-txn txnid] 42 data 43 44db put 45 [-nooverwrite] 46 [-partial {doff dlen}] 47 [-txn txnid] 48 key data </pre> 49 <p> 50 The <span class="emphasis"><em>db</em></span> <span class="bold"><strong>put</strong></span> 51 command stores the specified key/data pair into the database. 52 </p> 53 <p> 54 The options are as follows: 55 </p> 56 <div class="itemizedlist"> 57 <ul type="disc"> 58 <li> 59 <p> 60 <span class="bold"><strong>-append</strong></span> 61 </p> 62 <p> 63 Append the data item to the end of the database. For the <span class="bold"><strong>-append</strong></span> option to be specified, the underlying 64 database must be a Queue or Recno database. The record number 65 allocated to the record is returned on success. 66 </p> 67 </li> 68 <li> 69 <p> 70 <span class="bold"><strong>-nooverwrite</strong></span> 71 </p> 72 <p> 73 Enter the new key/data pair only if the key does not already appear in 74 the database. 75 </p> 76 </li> 77 <li> 78 <p> 79 <span class="bold"><strong>-partial {doff dlen}</strong></span> 80 </p> 81 <p> 82 The <span class="bold"><strong>dlen</strong></span> bytes starting <span class="bold"><strong>doff</strong></span> bytes from the beginning of the specified 83 key's data record are replaced by the data specified by the data and 84 size structure elements. If <span class="bold"><strong>dlen</strong></span> is 85 smaller than the length of the supplied data, the record will grow; if 86 <span class="bold"><strong>dlen</strong></span> is larger than the length of the 87 supplied data, the record will shrink. If the specified bytes do not 88 exist, the record will be extended using nul bytes as necessary, and 89 the <span class="emphasis"><em>db</em></span> <span class="bold"><strong>put</strong></span> call 90 will succeed. 91 </p> 92 <p> 93 It is an error to attempt a partial put using the 94 <span class="emphasis"><em>db</em></span> <span class="bold"><strong>put</strong></span> command 95 in a database that supports duplicate records. Partial puts in 96 databases supporting duplicate records must be done using a 97 <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> command. 98 </p> 99 <p> 100 It is an error to attempt a partial put with differing <span class="bold"><strong>dlen</strong></span> and supplied data length values in Queue 101 or Recno databases with fixed-length records. 102 </p> 103 </li> 104 <li> 105 <p> 106 <span class="bold"><strong>-txn txnid</strong></span> 107 </p> 108 <p> 109 If the operation is part of an application-specified transaction, the 110 <span class="bold"><strong>txnid</strong></span> parameter is a transaction 111 handle returned from <span class="emphasis"><em>env</em></span> <span class="bold"><strong>txn</strong></span>. If no transaction handle is specified, 112 but the operation occurs in a transactional database, the operation 113 will be implicitly transaction protected. 114 </p> 115 </li> 116 </ul> 117 </div> 118 <p> 119 The <span class="emphasis"><em>db</em></span> <span class="bold"><strong>put</strong></span> 120 command returns either 0 or a record number for success (the record 121 number is returned if the <span class="bold"><strong>-append</strong></span> 122 option was specified). If an error occurs, a Berkeley DB error message 123 is returned or a Tcl error is thrown. 124 </p> 125 <p> 126 If the underlying database is a Queue or Recno database, then the 127 given key will be interpreted by Tcl as an integer. For all other 128 database types, the key is interpreted by Tcl as a byte array. 129 </p> 130 </div> 131 <div class="navfooter"> 132 <hr /> 133 <table width="100%" summary="Navigation footer"> 134 <tr> 135 <td width="40%" align="left"><a accesskey="p" href="db_open.html">Prev</a>��</td> 136 <td width="20%" align="center"> 137 <a accesskey="u" href="tclapi.html">Up</a> 138 </td> 139 <td width="40%" align="right">��<a accesskey="n" href="db_remove.html">Next</a></td> 140 </tr> 141 <tr> 142 <td width="40%" align="left" valign="top">berkdb open��</td> 143 <td width="20%" align="center"> 144 <a accesskey="h" href="index.html">Home</a> 145 </td> 146 <td width="40%" align="right" valign="top">��berkdb dbremove</td> 147 </tr> 148 </table> 149 </div> 150 </body> 151</html> 152