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::set_append_recno()</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 C++ API Reference" /> 10 <link rel="up" href="db.html" title="Chapter 2. The Db Handle" /> 11 <link rel="prev" href="dbset_alloc.html" title="Db::set_alloc()" /> 12 <link rel="next" href="dbset_bt_compare.html" title="Db::set_bt_compare()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Db::set_append_recno()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="dbset_alloc.html">Prev</a> </td> 22 <th width="60%" align="center">Chapter 2. 23 The Db Handle 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="dbset_bt_compare.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="dbset_append_recno"></a>Db::set_append_recno()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40int 41Db::set_append_recno(int (*db_append_recno_fcn)(DB *dbp, Dbt *data, db_recno_t recno));</pre> 42 <p> 43 When using the <a class="link" href="dbput.html#dbput_DB_APPEND">DB_APPEND</a> 44 option of the <a class="xref" href="dbput.html" title="Db::put()">Db::put()</a> method, it may be 45 useful to modify the stored data based on the generated key. If a 46 callback function is specified using the 47 <code class="methodname">Db::set_append_recno()</code> 48 method, it will be called after the record number has been selected, 49 but before the data has been stored. 50 </p> 51 <p> 52 The <code class="methodname">Db::set_append_recno()</code> method configures operations performed 53 using the specified <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> 54 handle, not all operations performed on the underlying database. 55 </p> 56 <p> 57 The <code class="methodname">Db::set_append_recno()</code> method may not be called after the 58 <a class="xref" href="dbopen.html" title="Db::open()">Db::open()</a> method is called. 59 </p> 60 <p> 61 The <code class="methodname">Db::set_append_recno()</code> <span> 62 63 <span> 64 method either returns a non-zero error value or throws an 65 exception that encapsulates a non-zero error value on 66 failure, and returns 0 on success. 67 </span> 68 </span> 69 </p> 70 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 71 <h3 class="title">Note</h3> 72 <p> 73 Berkeley DB is not re-entrant. Callback functions should not attempt to make 74 library calls (for example, to release locks or close open handles). Re-entering 75 Berkeley DB is not guaranteed to work correctly, and the results are undefined. 76 </p> 77 </div> 78 <div class="sect2" lang="en" xml:lang="en"> 79 <div class="titlepage"> 80 <div> 81 <div> 82 <h3 class="title"><a id="id1642960"></a>Parameters</h3> 83 </div> 84 </div> 85 </div> 86 <div class="sect3" lang="en" xml:lang="en"> 87 <div class="titlepage"> 88 <div> 89 <div> 90 <h4 class="title"><a id="id1642860"></a>db_append_recno_fcn</h4> 91 </div> 92 </div> 93 </div> 94 <p> 95 The <span class="bold"><strong>db_append_recno_fcn</strong></span> parameter is 96 a function to call after the record number has been selected but 97 before the data has been stored into the database. The function takes 98 three parameters: 99 </p> 100 <div class="itemizedlist"> 101 <ul type="disc"> 102 <li> 103 <p> 104 <code class="literal">dbp</code> 105 </p> 106 <p> 107 The <span class="bold"><strong>dbp</strong></span> parameter is the enclosing 108 database handle. 109 </p> 110 </li> 111 <li> 112 <p> 113 <code class="literal">data</code> 114 </p> 115 <p> 116 The <span class="bold"><strong>data</strong></span> parameter is the data 117 <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> to be stored. 118 </p> 119 </li> 120 <li> 121 <p> 122 <code class="literal">recno</code> 123 </p> 124 <p> 125 The <span class="bold"><strong>recno</strong></span> parameter is the generated 126 record number. 127 </p> 128 </li> 129 </ul> 130 </div> 131 <p> 132 The called function may modify the data 133 <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a>. If the function needs to allocate 134 memory for the <span class="bold"><strong>data</strong></span> field, the 135 <span class="bold"><strong>flags</strong></span> field of 136 the returned <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> 137 should be set to <code class="literal">DB_DBT_APPMALLOC</code>, which indicates that 138 Berkeley DB should free the memory when it is done with it. 139 </p> 140 <p> 141 The callback function must return 0 on success and 142 <span class="bold"><strong>errno</strong></span> or a value outside of 143 the Berkeley DB error name space on failure. 144 </p> 145 </div> 146 </div> 147 <div class="sect2" lang="en" xml:lang="en"> 148 <div class="titlepage"> 149 <div> 150 <div> 151 <h3 class="title"><a id="id1643387"></a>Errors</h3> 152 </div> 153 </div> 154 </div> 155 <p> 156 The <code class="methodname">Db::set_append_recno()</code> <span> 157 158 <span> 159 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 160 exception, encapsulating one of the following non-zero errors, or return one 161 of the following non-zero errors: 162 </span> 163 </span> 164 </p> 165 <div class="sect3" lang="en" xml:lang="en"> 166 <div class="titlepage"> 167 <div> 168 <div> 169 <h4 class="title"><a id="id1643237"></a>EINVAL</h4> 170 </div> 171 </div> 172 </div> 173 <p> 174 If the method was called after <a class="xref" href="dbopen.html" title="Db::open()">Db::open()</a> 175 was called; or if an invalid flag value or parameter was specified. 176 </p> 177 </div> 178 </div> 179 <div class="sect2" lang="en" xml:lang="en"> 180 <div class="titlepage"> 181 <div> 182 <div> 183 <h3 class="title"><a id="id1643238"></a>Class</h3> 184 </div> 185 </div> 186 </div> 187 <p> 188 <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> 189 </p> 190 </div> 191 <div class="sect2" lang="en" xml:lang="en"> 192 <div class="titlepage"> 193 <div> 194 <div> 195 <h3 class="title"><a id="id1642858"></a>See Also</h3> 196 </div> 197 </div> 198 </div> 199 <p> 200 <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 201 </p> 202 </div> 203 </div> 204 <div class="navfooter"> 205 <hr /> 206 <table width="100%" summary="Navigation footer"> 207 <tr> 208 <td width="40%" align="left"><a accesskey="p" href="dbset_alloc.html">Prev</a> </td> 209 <td width="20%" align="center"> 210 <a accesskey="u" href="db.html">Up</a> 211 </td> 212 <td width="40%" align="right"> <a accesskey="n" href="dbset_bt_compare.html">Next</a></td> 213 </tr> 214 <tr> 215 <td width="40%" align="left" valign="top">Db::set_alloc() </td> 216 <td width="20%" align="center"> 217 <a accesskey="h" href="index.html">Home</a> 218 </td> 219 <td width="40%" align="right" valign="top"> Db::set_bt_compare()</td> 220 </tr> 221 </table> 222 </div> 223 </body> 224</html> 225