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>Dbc::dup()</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="dbc.html" title="Chapter 3. The Dbc Handle" /> 11 <link rel="prev" href="dbcdel.html" title="Dbc::del()" /> 12 <link rel="next" href="dbcget.html" title="Dbc::get()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Dbc::dup()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="dbcdel.html">Prev</a> </td> 22 <th width="60%" align="center">Chapter 3. 23 The Dbc Handle 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="dbcget.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="dbcdup"></a>Dbc::dup()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40int 41Dbc::dup(Dbc **cursorp, u_int32_t flags);</pre> 42 <p> 43 The <code class="methodname">Dbc::dup()</code> method creates a new cursor that uses the same 44 transaction and locker ID as the original cursor. This is useful when 45 an application is using locking and requires two or more cursors in 46 the same thread of control. 47 </p> 48 <p> 49 The <code class="methodname">Dbc::dup()</code> <span> 50 51 <span> 52 method either returns a non-zero error value or throws an 53 exception that encapsulates a non-zero error value on 54 failure, and returns 0 on success. 55 </span> 56 </span> 57 </p> 58 <div class="sect2" lang="en" xml:lang="en"> 59 <div class="titlepage"> 60 <div> 61 <div> 62 <h3 class="title"><a id="id1655909"></a>Parameters</h3> 63 </div> 64 </div> 65 </div> 66 <div class="sect3" lang="en" xml:lang="en"> 67 <div class="titlepage"> 68 <div> 69 <div> 70 <h4 class="title"><a id="id1655663"></a>cursorp</h4> 71 </div> 72 </div> 73 </div> 74 <p> 75 The <code class="methodname">Dbc::dup()</code> method 76 returns the newly created cursor in 77 <span class="bold"><strong>cursorp</strong></span>. 78 </p> 79 </div> 80 <div class="sect3" lang="en" xml:lang="en"> 81 <div class="titlepage"> 82 <div> 83 <div> 84 <h4 class="title"><a id="id1655694"></a>flags</h4> 85 </div> 86 </div> 87 </div> 88 <p> 89 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 90 or the following flag: 91 </p> 92 <div class="itemizedlist"> 93 <ul type="disc"> 94 <li> 95 <p><a id="dup_DB_POSITION"></a> 96 <code class="literal">DB_POSITION</code> 97 </p> 98 <p> 99 The newly created cursor is initialized to refer to the same position 100 in the database as the original cursor (if any) and hold the same 101 locks (if any). If the DB_POSITION flag is not specified, or the 102 original cursor does not hold a database position and locks, the 103 created cursor is uninitialized and will behave like a cursor newly 104 created using the <a class="xref" href="dbcursor.html" title="Db::cursor()">Db::cursor()</a> 105 method. 106 </p> 107 </li> 108 </ul> 109 </div> 110 </div> 111 </div> 112 <div class="sect2" lang="en" xml:lang="en"> 113 <div class="titlepage"> 114 <div> 115 <div> 116 <h3 class="title"><a id="id1656104"></a>Errors</h3> 117 </div> 118 </div> 119 </div> 120 <p> 121 The <code class="methodname">Dbc::dup()</code> <span> 122 123 <span> 124 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 125 exception, encapsulating one of the following non-zero errors, or return one 126 of the following non-zero errors: 127 </span> 128 </span> 129 </p> 130 <div class="sect3" lang="en" xml:lang="en"> 131 <div class="titlepage"> 132 <div> 133 <div> 134 <h4 class="title"><a id="id1655368"></a><span>DbRepHandleDeadException or</span> DB_REP_HANDLE_DEAD</h4> 135 </div> 136 </div> 137 </div> 138 <p> 139 When a client synchronizes with the master, it is possible for committed 140 transactions to be rolled back. This invalidates all the database and cursor 141 handles opened in the replication environment. Once this occurs, an attempt to use 142 such a handle will 143 <span> 144 throw a <a class="xref" href="dbrephandledead.html" title="DbRepHandleDeadException">DbRepHandleDeadException</a> (if 145 your application is configured to throw exceptions), or 146 </span> 147 return <code class="literal">DB_REP_HANDLE_DEAD</code>. 148 The application will need to discard the handle and open a new one in order to 149 continue processing. 150 </p> 151 </div> 152 <div class="sect3" lang="en" xml:lang="en"> 153 <div class="titlepage"> 154 <div> 155 <div> 156 <h4 class="title"><a id="id1655369"></a><span>DbDeadlockException or </span>DB_REP_LOCKOUT</h4> 157 </div> 158 </div> 159 </div> 160 <p> 161 The operation was blocked by client/master synchronization. 162 </p> 163 <p> 164 <a class="xref" href="dbdeadlock.html" title="DbDeadlockException">DbDeadlockException</a> is thrown if 165 your Berkeley DB API is configured to throw exceptions. 166 Otherwise, <code class="literal">DB_REP_LOCKOUT</code> is returned. 167 </p> 168 </div> 169 <div class="sect3" lang="en" xml:lang="en"> 170 <div class="titlepage"> 171 <div> 172 <div> 173 <h4 class="title"><a id="id1656253"></a>EINVAL</h4> 174 </div> 175 </div> 176 </div> 177 <p> 178 An invalid flag value or parameter was specified. 179 </p> 180 </div> 181 </div> 182 <div class="sect2" lang="en" xml:lang="en"> 183 <div class="titlepage"> 184 <div> 185 <div> 186 <h3 class="title"><a id="id1656138"></a>Class</h3> 187 </div> 188 </div> 189 </div> 190 <p> 191 <a class="link" href="dbc.html" title="Chapter 3. The Dbc Handle">Dbc</a> 192 </p> 193 </div> 194 <div class="sect2" lang="en" xml:lang="en"> 195 <div class="titlepage"> 196 <div> 197 <div> 198 <h3 class="title"><a id="id1655954"></a>See Also</h3> 199 </div> 200 </div> 201 </div> 202 <p> 203 <a class="xref" href="dbc.html#dbclist" title="Database Cursors and Related Methods">Database Cursors and Related Methods</a> 204 </p> 205 </div> 206 </div> 207 <div class="navfooter"> 208 <hr /> 209 <table width="100%" summary="Navigation footer"> 210 <tr> 211 <td width="40%" align="left"><a accesskey="p" href="dbcdel.html">Prev</a> </td> 212 <td width="20%" align="center"> 213 <a accesskey="u" href="dbc.html">Up</a> 214 </td> 215 <td width="40%" align="right"> <a accesskey="n" href="dbcget.html">Next</a></td> 216 </tr> 217 <tr> 218 <td width="40%" align="left" valign="top">Dbc::del() </td> 219 <td width="20%" align="center"> 220 <a accesskey="h" href="index.html">Home</a> 221 </td> 222 <td width="40%" align="right" valign="top"> Dbc::get()</td> 223 </tr> 224 </table> 225 </div> 226 </body> 227</html> 228