libdb/docs/api_reference/CXX/seqget.html
2011-09-13 13:44:24 -04:00

211 lines
9.6 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>DbSequence::get()</title>
<link rel="stylesheet" href="apiReference.css" type="text/css" />
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
<link rel="start" href="index.html" title="Berkeley DB C++ API Reference" />
<link rel="up" href="seq.html" title="Chapter 12.  The DbSequence Handle" />
<link rel="prev" href="seqclose.html" title="DbSequence::close()" />
<link rel="next" href="seqget_cachesize.html" title="DbSequence::get_cachesize()" />
</head>
<body>
<div xmlns="" class="navheader">
<div class="libver">
<p>Library Version 11.2.5.2</p>
</div>
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">DbSequence::get()</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="seqclose.html">Prev</a> </td>
<th width="60%" align="center">Chapter 12. 
The DbSequence Handle
</th>
<td width="20%" align="right"> <a accesskey="n" href="seqget_cachesize.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="seqget"></a>DbSequence::get()</h2>
</div>
</div>
</div>
<pre class="programlisting">#include &lt;db_cxx.h&gt;
int
DbSequence::get(DbTxn *txnid, int32_t delta, db_seq_t *retp,
u_int32_t flags);</pre>
<p>
The <code class="methodname">DbSequence::get()</code> method returns the next available element in
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
enough cached values in the sequence handle then they will be
returned. Otherwise the next value will be fetched from the database
and incremented (decremented) by enough to cover the <span class="bold"><strong>delta</strong></span> and the next batch of cached values.
</p>
<p>
For maximum concurrency a non-zero cache size should be specified
prior to opening the sequence handle and
<a class="link" href="envset_flags.html#envset_flags_DB_TXN_NOSYNC">DB_TXN_NOSYNC</a>
should be specified for each <code class="methodname">DbSequence::get()</code> method call.
</p>
<p>
By default, sequence ranges do not wrap; to cause the sequence to wrap
around the beginning or end of its range, specify the
<a class="link" href="seqset_flags.html#seqset_flags_DB_SEQ_WRAP">DB_SEQ_WRAP</a>
flag to the <a class="xref" href="seqset_flags.html" title="DbSequence::set_flags()">DbSequence::set_flags()</a>
method.
</p>
<p>
The <code class="methodname">DbSequence::get()</code> method will return EINVAL if the record in the
database is not a valid sequence record, or the sequence has reached
the beginning or end of its range and is not configured to wrap.
</p>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="id3667374"></a>Parameters</h3>
</div>
</div>
</div>
<div class="sect3" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id3667477"></a>txnid</h4>
</div>
</div>
</div>
<p>
If the operation is part of an application-specified transaction, the
<span class="bold"><strong>txnid</strong></span> parameter is a transaction
handle returned from <a class="xref" href="txnbegin.html" title="DbEnv::txn_begin()">DbEnv::txn_begin()</a>; if the
operation is part of a Berkeley DB Concurrent Data Store group, the
<span class="bold"><strong>txnid</strong></span> parameter is a handle returned
from <a class="xref" href="envcdsgroup_begin.html" title="DbEnv::cdsgroup_begin()">DbEnv::cdsgroup_begin()</a>;
otherwise NULL. If no transaction handle is specified, but the
operation occurs in a transactional database, the operation will be
implicitly transaction protected. No <span class="bold"><strong>txnid</strong></span> handle may be specified if the sequence
handle was opened with a non-zero cache size.
</p>
<p>
If the underlying database handle was opened in a transaction, calling
<code class="methodname">DbSequence::get()</code> may result in changes to the sequence object;
these changes will be automatically committed in a transaction
internal to the Berkeley DB library. If the thread of control calling
<code class="methodname">DbSequence::get()</code> has an active transaction, which holds locks on
the same database as the one in which the sequence object is stored,
it is possible for a thread of control calling <code class="methodname">DbSequence::get()</code> to
self-deadlock because the active transaction's locks conflict with the
internal transaction's locks. For this reason, it is often preferable
for sequence objects to be stored in their own database.
</p>
</div>
<div class="sect3" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id3667160"></a>delta</h4>
</div>
</div>
</div>
<p>
Specifies the amount to increment or decrement the sequence.
</p>
</div>
<div class="sect3" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id3667841"></a>retp</h4>
</div>
</div>
</div>
<p>
<span class="bold"><strong>retp</strong></span> points to the memory to hold the
return value from the sequence.
</p>
</div>
<div class="sect3" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id3654998"></a>flags</h4>
</div>
</div>
</div>
<p>
The <span class="bold"><strong>flags</strong></span> parameter must be set to 0
or by bitwise inclusively <span class="bold"><strong>OR</strong></span>'ing
together one or more of the following values:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
<code class="literal">DB_TXN_NOSYNC</code>
</p>
<p>
If the operation is implicitly transaction protected (the <span class="bold"><strong>txnid</strong></span> argument is NULL but the operation occurs
to a transactional database), do not synchronously flush the log when
the transaction commits.
</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="id3667769"></a>Class</h3>
</div>
</div>
</div>
<p>
<a class="link" href="seq.html" title="Chapter 12.  The DbSequence Handle">DbSequence</a>
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="id3667703"></a>See Also</h3>
</div>
</div>
</div>
<p>
<a class="xref" href="seq.html#seqlist" title="Sequences and Related Methods">Sequences and Related Methods</a>
</p>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="seqclose.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="seq.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="seqget_cachesize.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">DbSequence::close() </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> DbSequence::get_cachesize()</td>
</tr>
</table>
</div>
</body>
</html>