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_SEQUENCE->get()</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="seq.html" title="Chapter 11. The DB_SEQUENCE Handle" /> 11 <link rel="prev" href="seqclose.html" title="DB_SEQUENCE->close()" /> 12 <link rel="next" href="seqget_cachesize.html" title="DB_SEQUENCE->get_cachesize()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DB_SEQUENCE->get()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="seqclose.html">Prev</a> </td> 22 <th width="60%" align="center">Chapter 11. 23 The DB_SEQUENCE Handle 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="seqget_cachesize.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="seqget"></a>DB_SEQUENCE->get()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db.h> 39 40int 41DB_SEQUENCE->get(DB_SEQUENCE *seq, 42 DB_TXN *txnid, int32_t delta, db_seq_t *retp, u_int32_t flags); </pre> 43 <p> 44 The <code class="methodname">DB_SEQUENCE->get()</code> method returns the next available element in 45 the sequence and changes the sequence value by <span class="bold"><strong>delta</strong></span>. The value of <span class="bold"><strong>delta</strong></span> must be greater than zero. If there are 46 enough cached values in the sequence handle then they will be 47 returned. Otherwise the next value will be fetched from the database 48 and incremented (decremented) by enough to cover the <span class="bold"><strong>delta</strong></span> and the next batch of cached values. 49 </p> 50 <p> 51 For maximum concurrency a non-zero cache size should be specified 52 prior to opening the sequence handle and 53 <a class="link" href="envset_flags.html#envset_flags_DB_TXN_NOSYNC">DB_TXN_NOSYNC</a> 54 should be specified for each <code class="methodname">DB_SEQUENCE->get()</code> method call. 55 </p> 56 <p> 57 By default, sequence ranges do not wrap; to cause the sequence to wrap 58 around the beginning or end of its range, specify the 59 <a class="link" href="seqset_flags.html#seqset_flags_DB_SEQ_WRAP">DB_SEQ_WRAP</a> 60 flag to the <a class="xref" href="seqset_flags.html" title="DB_SEQUENCE->set_flags()">DB_SEQUENCE->set_flags()</a> 61 method. 62 </p> 63 <p> 64 The <code class="methodname">DB_SEQUENCE->get()</code> method will return EINVAL if the record in the 65 database is not a valid sequence record, or the sequence has reached 66 the beginning or end of its range and is not configured to wrap. 67 </p> 68 <div class="sect2" lang="en" xml:lang="en"> 69 <div class="titlepage"> 70 <div> 71 <div> 72 <h3 class="title"><a id="id1704669"></a>Parameters</h3> 73 </div> 74 </div> 75 </div> 76 <div class="sect3" lang="en" xml:lang="en"> 77 <div class="titlepage"> 78 <div> 79 <div> 80 <h4 class="title"><a id="id1704910"></a>delta</h4> 81 </div> 82 </div> 83 </div> 84 <p> 85 Specifies the amount to increment or decrement the sequence. 86 </p> 87 </div> 88 <div class="sect3" lang="en" xml:lang="en"> 89 <div class="titlepage"> 90 <div> 91 <div> 92 <h4 class="title"><a id="id1704984"></a>flags</h4> 93 </div> 94 </div> 95 </div> 96 <p> 97 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 98 or by bitwise inclusively <span class="bold"><strong>OR</strong></span>'ing 99 together one or more of the following values: 100 </p> 101 <div class="itemizedlist"> 102 <ul type="disc"> 103 <li> 104 <p> 105 <code class="literal">DB_TXN_NOSYNC</code> 106 </p> 107 <p> 108 If the operation is implicitly transaction protected (the <span class="bold"><strong>txnid</strong></span> argument is NULL but the operation occurs 109 to a transactional database), do not synchronously flush the log when 110 the transaction commits. 111 </p> 112 </li> 113 </ul> 114 </div> 115 </div> 116 <div class="sect3" lang="en" xml:lang="en"> 117 <div class="titlepage"> 118 <div> 119 <div> 120 <h4 class="title"><a id="id1704687"></a>retp</h4> 121 </div> 122 </div> 123 </div> 124 <p> 125 <span class="bold"><strong>retp</strong></span> points to the memory to hold the 126 return value from the sequence. 127 </p> 128 </div> 129 <div class="sect3" lang="en" xml:lang="en"> 130 <div class="titlepage"> 131 <div> 132 <div> 133 <h4 class="title"><a id="id1704981"></a>txnid</h4> 134 </div> 135 </div> 136 </div> 137 <p> 138 If the operation is part of an application-specified transaction, the 139 <span class="bold"><strong>txnid</strong></span> parameter is a transaction 140 handle returned from <a class="xref" href="txnbegin.html" title="DB_ENV->txn_begin()">DB_ENV->txn_begin()</a>; if the 141 operation is part of a Berkeley DB Concurrent Data Store group, the 142 <span class="bold"><strong>txnid</strong></span> parameter is a handle returned 143 from <a class="xref" href="envcdsgroup_begin.html" title="DB_ENV->cdsgroup_begin()">DB_ENV->cdsgroup_begin()</a>; 144 otherwise NULL. If no transaction handle is specified, but the 145 operation occurs in a transactional database, the operation will be 146 implicitly transaction protected. No <span class="bold"><strong>txnid</strong></span> handle may be specified if the sequence 147 handle was opened with a non-zero cache size. 148 </p> 149 <p> 150 If the underlying database handle was opened in a transaction, calling 151 <code class="methodname">DB_SEQUENCE->get()</code> may result in changes to the sequence object; 152 these changes will be automatically committed in a transaction 153 internal to the Berkeley DB library. If the thread of control calling 154 <code class="methodname">DB_SEQUENCE->get()</code> has an active transaction, which holds locks on 155 the same database as the one in which the sequence object is stored, 156 it is possible for a thread of control calling <code class="methodname">DB_SEQUENCE->get()</code> to 157 self-deadlock because the active transaction's locks conflict with the 158 internal transaction's locks. For this reason, it is often preferable 159 for sequence objects to be stored in their own database. 160 </p> 161 </div> 162 </div> 163 <div class="sect2" lang="en" xml:lang="en"> 164 <div class="titlepage"> 165 <div> 166 <div> 167 <h3 class="title"><a id="id1705203"></a>Class</h3> 168 </div> 169 </div> 170 </div> 171 <p> 172 <a class="link" href="seq.html" title="Chapter 11. The DB_SEQUENCE Handle">DB_SEQUENCE</a> 173 </p> 174 </div> 175 <div class="sect2" lang="en" xml:lang="en"> 176 <div class="titlepage"> 177 <div> 178 <div> 179 <h3 class="title"><a id="id1705047"></a>See Also</h3> 180 </div> 181 </div> 182 </div> 183 <p> 184 <a class="xref" href="seq.html#seqlist" title="Sequences and Related Methods">Sequences and Related Methods</a> 185 </p> 186 </div> 187 </div> 188 <div class="navfooter"> 189 <hr /> 190 <table width="100%" summary="Navigation footer"> 191 <tr> 192 <td width="40%" align="left"><a accesskey="p" href="seqclose.html">Prev</a> </td> 193 <td width="20%" align="center"> 194 <a accesskey="u" href="seq.html">Up</a> 195 </td> 196 <td width="40%" align="right"> <a accesskey="n" href="seqget_cachesize.html">Next</a></td> 197 </tr> 198 <tr> 199 <td width="40%" align="left" valign="top">DB_SEQUENCE->close() </td> 200 <td width="20%" align="center"> 201 <a accesskey="h" href="index.html">Home</a> 202 </td> 203 <td width="40%" align="right" valign="top"> DB_SEQUENCE->get_cachesize()</td> 204 </tr> 205 </table> 206 </div> 207 </body> 208</html> 209