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>Db::compact()</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="db.html" title="Chapter 2. The Db Handle" /> 11 <link rel="prev" href="dbcreate.html" title="Db" /> 12 <link rel="next" href="dbdel.html" title="Db::del()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Db::compact()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="dbcreate.html">Prev</a> </td> 22 <th width="60%" align="center">Chapter 2. 23 The Db Handle 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="dbdel.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="dbcompact"></a>Db::compact()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40int 41Db::compact(DbTxn *txnid, 42 Dbt *start, Dbt *stop, DB_COMPACT *c_data, u_int32_t flags, Dbt *end);</pre> 43 <p> 44 The <code class="methodname">Db::compact()</code> method compacts Btree and Recno access method 45 databases, and optionally returns unused Btree, Hash or Recno database 46 pages to the underlying filesystem. 47 </p> 48 <p> 49 The <code class="methodname">Db::compact()</code> <span> 50 51 <span> 52 method either returns a non-zero error value or throws an 53 exception that encapsulates a non-zero error value on 54 failure, and returns 0 on success. 55 </span> 56 </span> 57 </p> 58 <div class="sect2" lang="en" xml:lang="en"> 59 <div class="titlepage"> 60 <div> 61 <div> 62 <h3 class="title"><a id="id1631918"></a>Parameters</h3> 63 </div> 64 </div> 65 </div> 66 <div class="sect3" lang="en" xml:lang="en"> 67 <div class="titlepage"> 68 <div> 69 <div> 70 <h4 class="title"><a id="id1632250"></a>txnid</h4> 71 </div> 72 </div> 73 </div> 74 <p> 75 If the operation is part of an application-specified transaction, the 76 <span class="bold"><strong>txnid</strong></span> parameter is a transaction 77 handle returned from <a class="xref" href="txnbegin.html" title="DbEnv::txn_begin()">DbEnv::txn_begin()</a>; 78 if the operation is part of a Berkeley DB Concurrent Data Store group, the 79 <span class="bold"><strong>txnid</strong></span> parameter is a handle returned 80 from <a class="xref" href="envcdsgroup_begin.html" title="DbEnv::cdsgroup_begin()">DbEnv::cdsgroup_begin()</a>; 81 otherwise NULL. 82 </p> 83 <p> 84 If a transaction handle is supplied to this method, then the operation is 85 performed using that transaction. In this event, large sections of the 86 tree may be locked during the course of the transaction. 87 </p> 88 <p> 89 If no transaction handle is specified, but the operation occurs 90 in a transactional database, the operation will be implicitly 91 transaction protected using multiple transactions. These transactions 92 will be periodically committed to avoid locking large sections of the 93 tree. Any deadlocks encountered cause the compaction operation to 94 be retried from the point of the last transaction commit. 95 </p> 96 </div> 97 <div class="sect3" lang="en" xml:lang="en"> 98 <div class="titlepage"> 99 <div> 100 <div> 101 <h4 class="title"><a id="id1632434"></a>start</h4> 102 </div> 103 </div> 104 </div> 105 <p> 106 If non-NULL, the <span class="bold"><strong>start</strong></span> parameter is 107 the starting point for compaction in a Btree or Recno database. 108 Compaction will start at the smallest key greater than or equal to the 109 specified key. If NULL, compaction will start at the beginning of the 110 database. 111 </p> 112 </div> 113 <div class="sect3" lang="en" xml:lang="en"> 114 <div class="titlepage"> 115 <div> 116 <div> 117 <h4 class="title"><a id="id1632124"></a>stop</h4> 118 </div> 119 </div> 120 </div> 121 <p> 122 If non-NULL, the <span class="bold"><strong>stop</strong></span> parameter is 123 the stopping point for compaction in a Btree or Recno database. 124 Compaction will stop at the page with the smallest key greater than 125 the specified key. If NULL, compaction will stop at the end of the 126 database. 127 </p> 128 </div> 129 <div class="sect3" lang="en" xml:lang="en"> 130 <div class="titlepage"> 131 <div> 132 <div> 133 <h4 class="title"><a id="id1632541"></a>c_data</h4> 134 </div> 135 </div> 136 </div> 137 <p> 138 139 </p> 140 <p> 141 If non-NULL, the <span class="bold"><strong>c_data</strong></span> parameter 142 contains additional compaction configuration parameters, and returns 143 compaction operation statistics, in a structure of type DB_COMPACT. 144 </p> 145 <p> 146 The following input configuration fields are available from the 147 DB_COMPACT structure: 148 </p> 149 <div class="itemizedlist"> 150 <ul type="disc"> 151 <li> 152 <p> 153 <code class="literal">int compact_fillpercent;</code> 154 </p> 155 <p> 156 If non-zero, this provides the goal for filling pages, specified as a percentage 157 between 1 and 100. Any page in a Btree or Recno databases not at or 158 above this percentage full will be considered for compaction. The 159 default behavior is to consider every page for compaction, regardless 160 of its page fill percentage. 161 </p> 162 </li> 163 <li> 164 <p> 165 <code class="literal">int compact_pages;</code> 166 </p> 167 <p> 168 If non-zero, the call will return after the 169 specified number of pages have been freed, or 170 no more pages can be freed. 171 </p> 172 </li> 173 <li> 174 <p> 175 <code class="literal">db_timeout_t compact_timeout;</code> 176 </p> 177 <p> 178 If non-zero, and no <span class="bold"><strong>txnid</strong></span> parameter 179 was specified, this parameter identifies the lock timeout used for implicit transactions, in 180 microseconds. 181 </p> 182 </li> 183 </ul> 184 </div> 185 <p> 186 The following output statistics fields are available from the 187 <code class="literal">DB_COMPACT</code> structure: 188 </p> 189 <div class="itemizedlist"> 190 <ul type="disc"> 191 <li> 192 <p> 193 <code class="literal">u_int32_t compact_deadlock;</code> 194 </p> 195 <p> 196 An output statistics parameter: if no <span class="bold"><strong>txnid</strong></span> parameter was specified, the number of 197 deadlocks which occurred. 198 </p> 199 </li> 200 <li> 201 <p> 202 <code class="literal">u_int32_t compact_pages_examine;</code> 203 </p> 204 <p> 205 An output statistics parameter: the number of database pages reviewed 206 during the compaction phase. 207 </p> 208 </li> 209 <li> 210 <p> 211 <code class="literal">u_int32_t compact_pages_free;</code> 212 </p> 213 <p> 214 An output statistics parameter: the number of database pages freed 215 during the compaction phase. 216 </p> 217 </li> 218 <li> 219 <p> 220 <code class="literal">u_int32_t compact_levels;</code> 221 </p> 222 <p> 223 An output statistics parameter: the number of levels removed from the 224 Btree or Recno database during the compaction phase. 225 </p> 226 </li> 227 <li> 228 <p> 229 <code class="literal">u_int32_t compact_pages_truncated;</code> 230 </p> 231 <p> 232 An output statistics parameter: the number of database pages returned 233 to the filesystem. 234 </p> 235 </li> 236 </ul> 237 </div> 238 </div> 239 <div class="sect3" lang="en" xml:lang="en"> 240 <div class="titlepage"> 241 <div> 242 <div> 243 <h4 class="title"><a id="id1632258"></a>flags</h4> 244 </div> 245 </div> 246 </div> 247 <p> 248 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 249 or one of the following values: 250 </p> 251 <div class="itemizedlist"> 252 <ul type="disc"> 253 <li> 254 <p><a id="compact_DB_FREELIST_ONLY"></a> 255 <code class="literal">DB_FREELIST_ONLY</code> 256 </p> 257 <p> 258 Do no page compaction, only returning pages to the filesystem that are 259 already free and at the end of the file. This flag must be set if the 260 database is a Hash access method database. 261 </p> 262 </li> 263 <li> 264 <p><a id="compact_DB_FREE_SPACE"></a> 265 <code class="literal">DB_FREE_SPACE</code> 266 </p> 267 <p> 268 Return pages to the filesystem when possible. If this flag is not 269 specified, pages emptied as a result of compaction will be placed on 270 the free list for re-use, but never returned to the filesystem. 271 </p> 272 <p> 273 Note that only pages at the end of a file can be returned to the 274 filesystem. Because of the one-pass nature of the compaction 275 algorithm, any unemptied page near the end of the file inhibits 276 returning pages to the file system. A repeated call to the 277 <code class="methodname">Db::compact()</code> method with a low <span class="bold"><strong>compact_fillpercent</strong></span> may be used to return pages 278 in this case. 279 </p> 280 </li> 281 </ul> 282 </div> 283 </div> 284 <div class="sect3" lang="en" xml:lang="en"> 285 <div class="titlepage"> 286 <div> 287 <div> 288 <h4 class="title"><a id="id1632080"></a>end</h4> 289 </div> 290 </div> 291 </div> 292 <p> 293 If non-NULL, the <span class="bold"><strong>end</strong></span> parameter will 294 be filled in with the database key marking the end of the compaction 295 operation in a Btree or Recno database. This is generally the first 296 key of the page where the operation stopped. 297 </p> 298 </div> 299 </div> 300 <div class="sect2" lang="en" xml:lang="en"> 301 <div class="titlepage"> 302 <div> 303 <div> 304 <h3 class="title"><a id="id1632171"></a>Errors</h3> 305 </div> 306 </div> 307 </div> 308 <p> 309 The <code class="methodname">Db::compact()</code> <span> 310 311 <span> 312 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 313 exception, encapsulating one of the following non-zero errors, or return one 314 of the following non-zero errors: 315 </span> 316 </span> 317 </p> 318 <div class="sect3" lang="en" xml:lang="en"> 319 <div class="titlepage"> 320 <div> 321 <div> 322 <h4 class="title"><a id="id1632852"></a><span>DbDeadlockException or </span>DB_LOCK_DEADLOCK</h4> 323 </div> 324 </div> 325 </div> 326 <p> 327 A transactional database environment operation was selected to resolve 328 a deadlock. 329 </p> 330 <p> 331 <a class="xref" href="dbdeadlock.html" title="DbDeadlockException">DbDeadlockException</a> is thrown if 332 your Berkeley DB API is configured to throw exceptions. 333 Otherwise, <code class="literal">DB_LOCK_DEADLOCK</code> is returned. 334 </p> 335 </div> 336 <div class="sect3" lang="en" xml:lang="en"> 337 <div class="titlepage"> 338 <div> 339 <div> 340 <h4 class="title"><a id="id1632226"></a><span>DbLockNotGrantedException or </span>DB_LOCK_NOTGRANTED</h4> 341 </div> 342 </div> 343 </div> 344 <p> 345 A Berkeley DB Concurrent Data Store database environment configured 346 for lock timeouts was unable to grant a lock in the allowed time. 347 </p> 348 <p> 349 <a class="xref" href="dblocknotgranted.html" title="DbLockNotGrantedException">DbLockNotGrantedException</a> is thrown if 350 your Berkeley DB API is configured to throw exceptions. 351 Otherwise, <code class="literal">DB_LOCK_NOTGRANTED</code> is returned. 352 </p> 353 </div> 354 <div class="sect3" lang="en" xml:lang="en"> 355 <div class="titlepage"> 356 <div> 357 <div> 358 <h4 class="title"><a id="id1632482"></a><span>DbRepHandleDeadException or</span> DB_REP_HANDLE_DEAD</h4> 359 </div> 360 </div> 361 </div> 362 <p> 363 When a client synchronizes with the master, it is possible for committed 364 transactions to be rolled back. This invalidates all the database and cursor 365 handles opened in the replication environment. Once this occurs, an attempt to use 366 such a handle will 367 <span> 368 throw a <a class="xref" href="dbrephandledead.html" title="DbRepHandleDeadException">DbRepHandleDeadException</a> (if 369 your application is configured to throw exceptions), or 370 </span> 371 return <code class="literal">DB_REP_HANDLE_DEAD</code>. 372 The application will need to discard the handle and open a new one in order to 373 continue processing. 374 </p> 375 </div> 376 <div class="sect3" lang="en" xml:lang="en"> 377 <div class="titlepage"> 378 <div> 379 <div> 380 <h4 class="title"><a id="id1632623"></a><span>DbDeadlockException or </span>DB_REP_LOCKOUT</h4> 381 </div> 382 </div> 383 </div> 384 <p> 385 The operation was blocked by client/master synchronization. 386 </p> 387 <p> 388 <a class="xref" href="dbdeadlock.html" title="DbDeadlockException">DbDeadlockException</a> is thrown if 389 your Berkeley DB API is configured to throw exceptions. 390 Otherwise, <code class="literal">DB_REP_LOCKOUT</code> is returned. 391 </p> 392 </div> 393 <div class="sect3" lang="en" xml:lang="en"> 394 <div class="titlepage"> 395 <div> 396 <div> 397 <h4 class="title"><a id="id1632566"></a>EACCES</h4> 398 </div> 399 </div> 400 </div> 401 <p> 402 An attempt was made to modify a read-only database. 403 </p> 404 </div> 405 <div class="sect3" lang="en" xml:lang="en"> 406 <div class="titlepage"> 407 <div> 408 <div> 409 <h4 class="title"><a id="id1632564"></a>EINVAL</h4> 410 </div> 411 </div> 412 </div> 413 <p> 414 An invalid flag value or parameter was specified. 415 </p> 416 </div> 417 </div> 418 <div class="sect2" lang="en" xml:lang="en"> 419 <div class="titlepage"> 420 <div> 421 <div> 422 <h3 class="title"><a id="id1632880"></a>Class</h3> 423 </div> 424 </div> 425 </div> 426 <p> 427 <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> 428 </p> 429 </div> 430 <div class="sect2" lang="en" xml:lang="en"> 431 <div class="titlepage"> 432 <div> 433 <div> 434 <h3 class="title"><a id="id1632182"></a>See Also</h3> 435 </div> 436 </div> 437 </div> 438 <p> 439 <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 440 </p> 441 </div> 442 </div> 443 <div class="navfooter"> 444 <hr /> 445 <table width="100%" summary="Navigation footer"> 446 <tr> 447 <td width="40%" align="left"><a accesskey="p" href="dbcreate.html">Prev</a> </td> 448 <td width="20%" align="center"> 449 <a accesskey="u" href="db.html">Up</a> 450 </td> 451 <td width="40%" align="right"> <a accesskey="n" href="dbdel.html">Next</a></td> 452 </tr> 453 <tr> 454 <td width="40%" align="left" valign="top">Db </td> 455 <td width="20%" align="center"> 456 <a accesskey="h" href="index.html">Home</a> 457 </td> 458 <td width="40%" align="right" valign="top"> Db::del()</td> 459 </tr> 460 </table> 461 </div> 462 </body> 463</html> 464