docs/api_reference/CXX/seqstat.html

   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>DbSequence::stat()</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 12.  The DbSequence Handle" />
  11     <link rel="prev" href="seqset_range.html" title="DbSequence::set_range()" />
  12     <link rel="next" href="seqstat_print.html" title="DbSequence::stat_print()" />
  13   </head>
  14   <body>
  15     <div xmlns="" class="navheader">
  16       <div class="libver">
  17         <p>Library Version 11.2.5.3</p>
  18       </div>
  19       <table width="100%" summary="Navigation header">
  20         <tr>
  21           <th colspan="3" align="center">DbSequence::stat()</th>
  22         </tr>
  23         <tr>
  24           <td width="20%" align="left"><a accesskey="p" href="seqset_range.html">Prev</a> </td>
  25           <th width="60%" align="center">Chapter 12.
  26                 The DbSequence Handle
  27         </th>
  28           <td width="20%" align="right"> <a accesskey="n" href="seqstat_print.html">Next</a></td>
  29         </tr>
  30       </table>
  31       <hr />
  32     </div>
  33     <div class="sect1" lang="en" xml:lang="en">
  34       <div class="titlepage">
  35         <div>
  36           <div>
  37             <h2 class="title" style="clear: both"><a id="seqstat"></a>DbSequence::stat()</h2>
  38           </div>
  39         </div>
  40       </div>
  41       <pre class="programlisting">#include &lt;db_cxx.h&gt;
  42
  43 int
  44 DbSequence::stat(DB_SEQUENCE_STAT **spp, u_int32_t flags); </pre>
  45       <p>
  46          The <code class="methodname">DbSequence::stat()</code> method creates a statistical structure and
  47          copies a pointer to it into user-specified memory locations.
  48          Specifically, if <span class="bold"><strong>spp</strong></span> is non-NULL, a
  49          pointer to the statistics for the database are copied into the memory
  50          location to which it refers.
  51     </p>
  52       <p>
  53          Statistical structures are stored in allocated memory.  If
  54          application-specific allocation routines have been declared (see
  55          <a class="xref" href="envset_alloc.html" title="DbEnv::set_alloc()">DbEnv::set_alloc()</a>
  56          for more information), they are used to allocate the memory;
  57          otherwise, the standard C library <span class="bold"><strong>malloc</strong></span>(3) is used.  The caller is responsible
  58          for deallocating the memory.  To deallocate the memory, free the
  59          memory reference; references inside the returned memory need not be
  60          individually freed.
  61     </p>
  62       <p>
  63          In the presence of multiple threads or processes accessing an active
  64          sequence, the information returned by <code class="methodname">DbSequence::stat()</code> may be
  65          out-of-date.
  66     </p>
  67       <p>
  68          The <code class="methodname">DbSequence::stat()</code> method cannot be transaction-protected.  For
  69          this reason, it should be called in a thread of control that has no
  70          open cursors or active transactions.
  71     </p>
  72       <p>
  73          The <code class="methodname">DbSequence::stat()</code> <span>
  74
  75             <span>
  76                 method either returns a non-zero error value or throws an
  77                 exception that encapsulates a non-zero error value on
  78                 failure, and returns 0 on success.
  79             </span>
  80         </span>
  81      </p>
  82       <p>
  83          The statistics are stored in a structure of type <code class="literal">DB_SEQUENCE_STAT</code>.
  84          The following fields will be filled in:
  85     </p>
  86       <div class="itemizedlist">
  87         <ul type="disc">
  88           <li>
  89             <p>
  90                     <span class="bold"><strong>int32_t st_cache_size;</strong></span>
  91                 </p>
  92             <p>
  93                     The number of values that will be cached in this handle.
  94                 </p>
  95           </li>
  96           <li>
  97             <p>
  98                     <span class="bold"><strong>db_seq_t st_current;</strong></span>
  99                 </p>
 100             <p>
 101                     The current value of the sequence in the database.
 102                 </p>
 103           </li>
 104           <li>
 105             <p>
 106                     <span class="bold"><strong>u_int32_t st_flags;</strong></span>
 107                 </p>
 108             <p>
 109                     The flags value for the sequence.
 110                 </p>
 111           </li>
 112           <li>
 113             <p>
 114                     <span class="bold"><strong>db_seq_t st_last_value;</strong></span>
 115                 </p>
 116             <p>
 117                     The last cached value of the sequence.
 118                 </p>
 119           </li>
 120           <li>
 121             <p>
 122                     <span class="bold"><strong>db_seq_t st_min;</strong></span>
 123                 </p>
 124             <p>
 125                     The minimum permitted value of the sequence.
 126                 </p>
 127           </li>
 128           <li>
 129             <p>
 130                     <span class="bold"><strong>db_seq_t st_max;</strong></span>
 131                 </p>
 132             <p>
 133                     The maximum permitted value of the sequence.
 134                 </p>
 135           </li>
 136           <li>
 137             <p>
 138                     <span class="bold"><strong>uintmax_t st_nowait;</strong></span>
 139                 </p>
 140             <p>
 141                     The number of times that a thread of control was able to obtain handle
 142                     mutex without waiting.
 143                 </p>
 144           </li>
 145           <li>
 146             <p>
 147                     <span class="bold"><strong>db_seq_t st_value;</strong></span>
 148                 </p>
 149             <p>
 150                     The current cached value of the sequence.
 151                 </p>
 152           </li>
 153           <li>
 154             <p>
 155                     <span class="bold"><strong>uintmax_t st_wait;</strong></span>
 156                 </p>
 157             <p>
 158                     The number of times a thread of control was forced to wait on the
 159                     handle mutex.
 160                 </p>
 161           </li>
 162         </ul>
 163       </div>
 164       <div class="sect2" lang="en" xml:lang="en">
 165         <div class="titlepage">
 166           <div>
 167             <div>
 168               <h3 class="title"><a id="idp4845760"></a>Parameters</h3>
 169             </div>
 170           </div>
 171         </div>
 172         <div class="sect3" lang="en" xml:lang="en">
 173           <div class="titlepage">
 174             <div>
 175               <div>
 176                 <h4 class="title"><a id="idp4801376"></a>flags</h4>
 177               </div>
 178             </div>
 179           </div>
 180           <p>
 181                   The <span class="bold"><strong>flags</strong></span> parameter must be set by
 182                   bitwise inclusively <span class="bold"><strong>OR</strong></span>'ing together
 183                   one or more of the following values:
 184              </p>
 185           <div class="itemizedlist">
 186             <ul type="disc">
 187               <li>
 188                 <p>
 189                         <code class="literal">DB_STAT_ALL</code>
 190                     </p>
 191                 <p>
 192                         Display all available information.
 193                     </p>
 194               </li>
 195               <li>
 196                 <p>
 197                           <code class="literal">DB_STAT_CLEAR</code>
 198                     </p>
 199                 <p>
 200                         Reset statistics after printing their values.
 201                     </p>
 202               </li>
 203             </ul>
 204           </div>
 205         </div>
 206       </div>
 207       <div class="sect2" lang="en" xml:lang="en">
 208         <div class="titlepage">
 209           <div>
 210             <div>
 211               <h3 class="title"><a id="idp4852560"></a>Class</h3>
 212             </div>
 213           </div>
 214         </div>
 215         <p>
 216                  <a class="link" href="seq.html" title="Chapter 12.  The DbSequence Handle">DbSequence</a>
 217             </p>
 218       </div>
 219       <div class="sect2" lang="en" xml:lang="en">
 220         <div class="titlepage">
 221           <div>
 222             <div>
 223               <h3 class="title"><a id="idp4854032"></a>See Also</h3>
 224             </div>
 225           </div>
 226         </div>
 227         <p>
 228              <a class="xref" href="seq.html#seqlist" title="Sequences and Related Methods">Sequences and Related Methods</a>
 229         </p>
 230       </div>
 231     </div>
 232     <div class="navfooter">
 233       <hr />
 234       <table width="100%" summary="Navigation footer">
 235         <tr>
 236           <td width="40%" align="left"><a accesskey="p" href="seqset_range.html">Prev</a> </td>
 237           <td width="20%" align="center">
 238             <a accesskey="u" href="seq.html">Up</a>
 239           </td>
 240           <td width="40%" align="right"> <a accesskey="n" href="seqstat_print.html">Next</a></td>
 241         </tr>
 242         <tr>
 243           <td width="40%" align="left" valign="top">DbSequence::set_range() </td>
 244           <td width="20%" align="center">
 245             <a accesskey="h" href="index.html">Home</a>
 246           </td>
 247           <td width="40%" align="right" valign="top"> DbSequence::stat_print()</td>
 248         </tr>
 249       </table>
 250     </div>
 251   </body>
 252 </html>