1<!--$Id: seq_get.so,v 1.11 2005/08/09 14:23:30 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB: DB_SEQUENCE->get</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td> 13<b>DB_SEQUENCE->get</b> 14</td> 15<td align=right> 16<a href="../api_c/api_core.html"><img src="../images/api.gif" alt="API"></a> 17<a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a></td> 18</tr></table> 19<hr size=1 noshade> 20<tt> 21<b><pre> 22#include <db.h> 23<p> 24int 25DB_SEQUENCE->get(DB_SEQUENCE *seq, 26 DB_TXN *txnid, int32_t delta, db_seq_t *retp, u_int32_t flags); 27</pre></b> 28<hr size=1 noshade> 29<b>Description: DB_SEQUENCE->get</b> 30<p>The DB_SEQUENCE->get method returns the next available element in the sequence 31and changes the sequence value by <b>delta</b>. The value of 32<b>delta</b> must be greater than zero. If there are enough cached 33values in the sequence handle then they will be returned. Otherwise the 34next value will be fetched from the database and incremented 35(decremented) by enough to cover the <b>delta</b> and the next batch 36of cached values.</p> 37<p>For maximum concurrency a non-zero cache size should be specified prior 38to opening the sequence handle and <a href="../api_c/env_set_flags.html#DB_TXN_NOSYNC">DB_TXN_NOSYNC</a> should be 39specified for each DB_SEQUENCE->get method call.</p> 40<p>By default, sequence ranges do not wrap; to cause the sequence to wrap 41around the beginning or end of its range, specify the <a href="../api_c/seq_set_flags.html#DB_SEQ_WRAP">DB_SEQ_WRAP</a> 42flag to the <a href="../api_c/seq_set_flags.html">DB_SEQUENCE->set_flags</a> method.</p> 43<p>The DB_SEQUENCE->get method will return EINVAL if the record in the database is not a valid sequence 44record, or the sequence has reached the beginning or end of its range 45and is not configured to wrap. 46</p> 47<b>Parameters</b> <br> 48 <b>delta</b><ul compact><li>Specifies the amount to increment or decrement the sequence.</ul> 49 <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 50or more of the following values: 51<br> 52<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> 53argument is NULL but the operation occurs to a transactional database), 54do not synchronously flush the log when the transaction commits.</ul> 55<br></ul> 56 <b>retp</b><ul compact><li><b>retp</b> points to the memory to hold the return value from 57the sequence.</ul> 58 <b>txnid</b><ul compact><li>If the operation is part of an application-specified transaction, the 59<b>txnid</b> parameter is a transaction handle returned from 60<a href="../api_c/txn_begin.html">DB_ENV->txn_begin</a>; if the operation is part of a Berkeley DB Concurrent Data Store group, the 61<b>txnid</b> parameter is a handle returned from 62<a href="../api_c/env_cdsgroup_begin.html">DB_ENV->cdsgroup_begin</a>; otherwise NULL. 63If no transaction handle is 64specified, but the 65operation occurs in a transactional 66database, 67the operation will be implicitly transaction protected. 68No <b>txnid</b> handle may be specified if the sequence handle was 69opened with a non-zero cache size. 70<p>If the underlying database handle was opened in a transaction, calling 71DB_SEQUENCE->get may result in changes to the sequence object; these 72changes will be automatically committed in a transaction internal to the 73Berkeley DB library. If the thread of control calling DB_SEQUENCE->get has 74an active transaction, which holds locks on the same database as the 75one in which the sequence object is stored, it is possible for a thread 76of control calling DB_SEQUENCE->get to self-deadlock because the active 77transaction's locks conflict with the internal transaction's locks. 78For this reason, it is often preferable for sequence objects to be 79stored in their own database.</p></ul> 80<br> 81<hr size=1 noshade> 82<br><b>Class</b> 83<a href="../api_c/seq_class.html">DB_SEQUENCE</a> 84<br><b>See Also</b> 85<a href="../api_c/seq_list.html">Sequences and Related Methods</a> 86</tt> 87<table width="100%"><tr><td><br></td><td align=right> 88<a href="../api_c/api_core.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a> 89</td></tr></table> 90<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 91</body> 92</html> 93
