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>DbEnv::txn_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="txn.html" title="Chapter 13. The DbTxn Handle" /> 11 <link rel="prev" href="txnset_timeout.html" title="DbTxn::set_timeout()" /> 12 <link rel="next" href="txnstat_print.html" title="DbEnv::txn_stat_print()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DbEnv::txn_stat()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="txnset_timeout.html">Prev</a> </td> 22 <th width="60%" align="center">Chapter 13. 23 The DbTxn Handle 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="txnstat_print.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="txnstat"></a>DbEnv::txn_stat()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40int 41DbEnv::txn_stat(DB_TXN_STAT **statp, u_int32_t flags); </pre> 42 <p> 43 The <code class="methodname">DbEnv::txn_stat()</code> method returns the transaction subsystem 44 statistics. 45 </p> 46 <p> 47 The <code class="methodname">DbEnv::txn_stat()</code> method creates a statistical structure of type 48 <code class="literal">DB_TXN_STAT</code> and copies a pointer to it into a user-specified memory 49 location. 50 </p> 51 <p> 52 Statistical structures are stored in allocated memory. If 53 application-specific allocation routines have been declared (see 54 <a class="xref" href="envset_alloc.html" title="DbEnv::set_alloc()">DbEnv::set_alloc()</a> 55 for more information), they are used to allocate the memory; 56 otherwise, the standard C library <span class="bold"><strong>malloc</strong></span>(3) is used. The caller is responsible 57 for deallocating the memory. To deallocate the memory, free the 58 memory reference; references inside the returned memory need not be 59 individually freed. 60 </p> 61 <p> 62 The following DB_TXN_STAT fields will be filled in: 63 </p> 64 <div class="itemizedlist"> 65 <ul type="disc"> 66 <li> 67 <p> 68 <span class="bold"><strong>DB_LSN st_last_ckp;</strong></span> 69 </p> 70 <p> 71 The LSN of the last checkpoint. 72 </p> 73 </li> 74 <li> 75 <p> 76 <span class="bold"><strong>time_t st_time_ckp;</strong></span> 77 </p> 78 <p> 79 The time the last completed checkpoint finished (as the number of 80 seconds since the Epoch, returned by the IEEE/ANSI Std 1003.1 (POSIX) 81 <span class="bold"><strong>time</strong></span> function). 82 </p> 83 </li> 84 <li> 85 <p> 86 <span class="bold"><strong>u_int32_t st_last_txnid;</strong></span> 87 </p> 88 <p> 89 The last transaction ID allocated. 90 </p> 91 </li> 92 <li> 93 <p> 94 <span class="bold"><strong>u_int32_t st_maxtxns;</strong></span> 95 </p> 96 <p> 97 The maximum number of active transactions configured. 98 </p> 99 </li> 100 <li> 101 <p> 102 <span class="bold"><strong>u_int32_t st_nactive;</strong></span> 103 </p> 104 <p> 105 The number of transactions that are currently active. 106 </p> 107 </li> 108 <li> 109 <p> 110 <span class="bold"><strong>u_int32_t st_nsnapshot;</strong></span> 111 </p> 112 <p> 113 The number of transactions on the snapshot list. These are 114 transactions which modified a database opened with 115 <a class="link" href="dbopen.html#dbopen_DB_MULTIVERSION">DB_MULTIVERSION</a>, 116 and which have committed or aborted, but the copies of pages they 117 created are still in the cache. 118 </p> 119 </li> 120 <li> 121 <p> 122 <span class="bold"><strong>u_int32_t st_maxnactive;</strong></span> 123 </p> 124 <p> 125 The maximum number of active transactions at any one time. 126 </p> 127 </li> 128 <li> 129 <p> 130 <span class="bold"><strong>u_int32_t st_maxnsnapshot;</strong></span> 131 </p> 132 <p> 133 The maximum number of transactions on the snapshot list at any one 134 time. 135 </p> 136 </li> 137 <li> 138 <p> 139 <span class="bold"><strong>uintmax_t st_nbegins;</strong></span> 140 </p> 141 <p> 142 The number of transactions that have begun. 143 </p> 144 </li> 145 <li> 146 <p> 147 <span class="bold"><strong>uintmax_t st_naborts;</strong></span> 148 </p> 149 <p> 150 The number of transactions that have aborted. 151 </p> 152 </li> 153 <li> 154 <p> 155 <span class="bold"><strong>uintmax_t st_ncommits;</strong></span> 156 </p> 157 <p> 158 The number of transactions that have committed. 159 </p> 160 </li> 161 <li> 162 <p> 163 <span class="bold"><strong>u_int32_t st_nrestores;</strong></span> 164 </p> 165 <p> 166 The number of transactions that have been restored. 167 </p> 168 </li> 169 <li> 170 <p> 171 <span class="bold"><strong>roff_t st_regsize;</strong></span> 172 </p> 173 <p> 174 The size of the transaction region, in bytes. 175 </p> 176 </li> 177 <li> 178 <p> 179 <span class="bold"><strong>uintmax_t st_region_wait;</strong></span> 180 </p> 181 <p> 182 The number of times that a thread of control was forced to wait before 183 obtaining the transaction region mutex. 184 </p> 185 </li> 186 <li> 187 <p> 188 <span class="bold"><strong>uintmax_t st_region_nowait;</strong></span> 189 </p> 190 <p> 191 The number of times that a thread of control was able to obtain the 192 transaction region mutex without waiting. 193 </p> 194 </li> 195 <li> 196 <p> 197 <span class="bold"><strong>DB_TXN_ACTIVE *st_txnarray;</strong></span> 198 </p> 199 <p> 200 A pointer to an array of <span class="bold"><strong>st_nactive</strong></span> 201 DB_TXN_ACTIVE structures, describing the currently active 202 transactions. The following fields of the DB_TXN_ACTIVE structure will 203 be filled in: 204 </p> 205 <div class="itemizedlist"> 206 <ul type="circle"> 207 <li> 208 <p> 209 <span class="bold"><strong>u_int32_t txnid;</strong></span> 210 </p> 211 <p> 212 The transaction ID of the transaction. 213 </p> 214 </li> 215 <li> 216 <p> 217 <span class="bold"><strong>u_int32_t parentid;</strong></span> 218 </p> 219 <p> 220 The transaction ID of the parent transaction (or 0, if no parent). 221 </p> 222 </li> 223 <li> 224 <p> 225 <span class="bold"><strong>pid_t pid;</strong></span> 226 </p> 227 <p> 228 The process ID of the originator of the transaction. 229 </p> 230 </li> 231 <li> 232 <p> 233 <span class="bold"><strong>db_threadid_t tid;</strong></span> 234 </p> 235 <p> 236 The thread of control ID of the originator of the transaction. 237 </p> 238 </li> 239 <li> 240 <p> 241 <span class="bold"><strong>DB_LSN lsn;</strong></span> 242 </p> 243 <p> 244 The current log sequence number when the transaction was begun. 245 </p> 246 </li> 247 <li> 248 <p> 249 <span class="bold"><strong>DB_LSN read_lsn;</strong></span> 250 </p> 251 <p> 252 The log sequence number of reads for snapshot transactions. 253 </p> 254 </li> 255 <li> 256 <p> 257 <span class="bold"><strong>u_int32_t mvcc_ref;</strong></span> 258 </p> 259 <p> 260 The number of buffer copies created by this transaction that remain 261 in cache. 262 </p> 263 </li> 264 <li> 265 <p> 266 <span class="bold"><strong>u_int32_t status;</strong></span> 267 </p> 268 <p> 269 One of the following list of constants: TXN_ABORTED, TXN_COMMITTED, 270 TXN_PREPARED, TXN_RUNNING. 271 </p> 272 </li> 273 <li> 274 <p> 275 <span class="bold"><strong>u_int8_t gid[DB_GID_SIZE];</strong></span> 276 </p> 277 <p> 278 If the transaction was prepared using 279 <a class="xref" href="txnprepare.html" title="DbTxn::prepare()">DbTxn::prepare()</a>, then 280 <span class="bold"><strong>gid</strong></span> contains the 281 transaction's Global ID. Otherwise, 282 <span class="bold"><strong>gid's</strong></span> contents are undefined. 283 </p> 284 </li> 285 <li> 286 <p> 287 <span class="bold"><strong>char name[];</strong></span> 288 </p> 289 <p> 290 If a name was specified for the transaction, up to the first 50 bytes 291 of that name, followed by a nul termination byte. 292 </p> 293 </li> 294 </ul> 295 </div> 296 </li> 297 </ul> 298 </div> 299 <p> 300 The <code class="methodname">DbEnv::txn_stat()</code> method may not be called before the 301 <a class="xref" href="envopen.html" title="DbEnv::open()">DbEnv::open()</a> method is called. 302 </p> 303 <p> 304 The <code class="methodname">DbEnv::txn_stat()</code> <span> 305 306 <span> 307 method either returns a non-zero error value or throws an 308 exception that encapsulates a non-zero error value on 309 failure, and returns 0 on success. 310 </span> 311 </span> 312 </p> 313 <div class="sect2" lang="en" xml:lang="en"> 314 <div class="titlepage"> 315 <div> 316 <div> 317 <h3 class="title"><a id="id1715766"></a>Parameters</h3> 318 </div> 319 </div> 320 </div> 321 <div class="sect3" lang="en" xml:lang="en"> 322 <div class="titlepage"> 323 <div> 324 <div> 325 <h4 class="title"><a id="id1716394"></a>flags</h4> 326 </div> 327 </div> 328 </div> 329 <p> 330 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 331 or the following value: 332 </p> 333 <div class="itemizedlist"> 334 <ul type="disc"> 335 <li> 336 <p> 337 <code class="literal">DB_STAT_CLEAR</code> 338 </p> 339 <p> 340 Reset statistics after returning their values. 341 </p> 342 </li> 343 </ul> 344 </div> 345 </div> 346 <div class="sect3" lang="en" xml:lang="en"> 347 <div class="titlepage"> 348 <div> 349 <div> 350 <h4 class="title"><a id="id1716553"></a>statp</h4> 351 </div> 352 </div> 353 </div> 354 <p> 355 The <span class="bold"><strong>statp</strong></span> parameter references memory 356 into which a pointer to the allocated statistics structure is copied. 357 </p> 358 </div> 359 </div> 360 <div class="sect2" lang="en" xml:lang="en"> 361 <div class="titlepage"> 362 <div> 363 <div> 364 <h3 class="title"><a id="id1716447"></a>Errors</h3> 365 </div> 366 </div> 367 </div> 368 <p> 369 The <code class="methodname">DbEnv::txn_stat()</code> <span> 370 371 <span> 372 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 373 exception, encapsulating one of the following non-zero errors, or return one 374 of the following non-zero errors: 375 </span> 376 </span> 377 </p> 378 <div class="sect3" lang="en" xml:lang="en"> 379 <div class="titlepage"> 380 <div> 381 <div> 382 <h4 class="title"><a id="id1716462"></a>EINVAL</h4> 383 </div> 384 </div> 385 </div> 386 <p> 387 An invalid flag value or parameter was specified. 388 </p> 389 </div> 390 </div> 391 <div class="sect2" lang="en" xml:lang="en"> 392 <div class="titlepage"> 393 <div> 394 <div> 395 <h3 class="title"><a id="id1715807"></a>Class</h3> 396 </div> 397 </div> 398 </div> 399 <p> 400 <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a>, <a class="link" href="txn.html" title="Chapter 13. The DbTxn Handle">DbTxn</a> 401 </p> 402 </div> 403 <div class="sect2" lang="en" xml:lang="en"> 404 <div class="titlepage"> 405 <div> 406 <div> 407 <h3 class="title"><a id="id1716014"></a>See Also</h3> 408 </div> 409 </div> 410 </div> 411 <p> 412 <a class="xref" href="txn.html#txnlist" title="Transaction Subsystem and Related Methods">Transaction Subsystem and Related Methods</a> 413 </p> 414 </div> 415 </div> 416 <div class="navfooter"> 417 <hr /> 418 <table width="100%" summary="Navigation footer"> 419 <tr> 420 <td width="40%" align="left"><a accesskey="p" href="txnset_timeout.html">Prev</a> </td> 421 <td width="20%" align="center"> 422 <a accesskey="u" href="txn.html">Up</a> 423 </td> 424 <td width="40%" align="right"> <a accesskey="n" href="txnstat_print.html">Next</a></td> 425 </tr> 426 <tr> 427 <td width="40%" align="left" valign="top">DbTxn::set_timeout() </td> 428 <td width="20%" align="center"> 429 <a accesskey="h" href="index.html">Home</a> 430 </td> 431 <td width="40%" align="right" valign="top"> DbEnv::txn_stat_print()</td> 432 </tr> 433 </table> 434 </div> 435 </body> 436</html> 437