<!--$Id: seq_get.so,v 1.11 2005/08/09 14:23:30 bostic Exp $--> <!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> <!--See the file LICENSE for redistribution information.--> <html> <head> <title>Berkeley DB: DbSequence::get</title> <meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> <meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> </head> <body bgcolor=white> <table width="100%"><tr valign=top> <td> <b>DbSequence::get</b> </td> <td align=right> <a href="../api_cxx/api_core.html"><img src="../images/api.gif" alt="API"></a> <a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a></td> </tr></table> <hr size=1 noshade> <tt> <b><pre> #include <db_cxx.h> <p> int DbSequence::get(DbTxn *txnid, int32_t delta, db_seq_t *retp, u_int32_t flags); </pre></b> <hr size=1 noshade> <b>Description: DbSequence::get</b> <p>The DbSequence::get method returns the next available element in the sequence and changes the sequence value by <b>delta</b>. The value of <b>delta</b> 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 <b>delta</b> 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 href="../api_cxx/env_set_flags.html#DB_TXN_NOSYNC">DB_TXN_NOSYNC</a> should be specified for each DbSequence::get 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 href="../api_cxx/seq_set_flags.html#DB_SEQ_WRAP">DB_SEQ_WRAP</a> flag to the <a href="../api_cxx/seq_set_flags.html">DbSequence::set_flags</a> method.</p> <p>The DbSequence::get 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> <b>Parameters</b> <br> <b>delta</b><ul compact><li>Specifies the amount to increment or decrement the sequence.</ul> <b>flags</b><ul compact><li>The <b>flags</b> parameter must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one or more of the following values: <br> <b><a name="DB_TXN_NOSYNC">DB_TXN_NOSYNC</a></b><ul compact><li>If the operation is implicitly transaction protected (the <b>txnid</b> argument is NULL but the operation occurs to a transactional database), do not synchronously flush the log when the transaction commits.</ul> <br></ul> <b>retp</b><ul compact><li><b>retp</b> points to the memory to hold the return value from the sequence.</ul> <b>txnid</b><ul compact><li>If the operation is part of an application-specified transaction, the <b>txnid</b> parameter is a transaction handle returned from <a href="../api_cxx/txn_begin.html">DbEnv::txn_begin</a>; if the operation is part of a Berkeley DB Concurrent Data Store group, the <b>txnid</b> parameter is a handle returned from <a href="../api_cxx/env_cdsgroup_begin.html">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 <b>txnid</b> handle may be specified if the sequence handle was opened with a non-zero cache size. <p>If the underlying database handle was opened in a transaction, calling DbSequence::get 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 DbSequence::get 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 DbSequence::get 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></ul> <br> <hr size=1 noshade> <br><b>Class</b> <a href="../api_cxx/seq_class.html">DbSequence</a> <br><b>See Also</b> <a href="../api_cxx/seq_list.html">Sequences and Related Methods</a> </tt> <table width="100%"><tr><td><br></td><td align=right> <a href="../api_cxx/api_core.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a> </td></tr></table> <p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> </body> </html>