File: bt_conf.html

package info (click to toggle)
db5.3 5.3.28%2Bdfsg1-0.5
links: PTS, VCS
area: main
in suites: buster
size: 158,360 kB
sloc: ansic: 448,411; java: 111,824; tcl: 80,544; sh: 44,326; cs: 33,697; cpp: 21,604; perl: 14,557; xml: 10,799; makefile: 4,077; yacc: 1,003; awk: 965; sql: 801; erlang: 342; python: 216; php: 24; asm: 14
file content (711 lines) | stat: -rw-r--r-- 30,661 bytes
parent folder | download | duplicates (8)
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Btree access method specific configuration</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="am_conf.html" title="Chapter 2.  Access Method Configuration" />
    <link rel="prev" href="general_am_conf.html" title="General access method configuration" />
    <link rel="next" href="hash_conf.html" title="Hash access method specific configuration" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 11.2.5.3</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Btree access method specific configuration</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="general_am_conf.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 2. 
		Access Method Configuration
        </th>
          <td width="20%" align="right"> <a accesskey="n" href="hash_conf.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="bt_conf"></a>Btree access method specific configuration</h2>
          </div>
        </div>
      </div>
      <div class="toc">
        <dl>
          <dt>
            <span class="sect2">
              <a href="bt_conf.html#am_conf_bt_compare">Btree comparison</a>
            </span>
          </dt>
          <dt>
            <span class="sect2">
              <a href="bt_conf.html#am_conf_bt_prefix">Btree prefix comparison</a>
            </span>
          </dt>
          <dt>
            <span class="sect2">
              <a href="bt_conf.html#am_conf_bt_minkey">Minimum keys per page</a>
            </span>
          </dt>
          <dt>
            <span class="sect2">
              <a href="bt_conf.html#am_conf_bt_recnum">Retrieving Btree records by logical record number</a>
            </span>
          </dt>
          <dt>
            <span class="sect2">
              <a href="bt_conf.html#am_conf_bt_compress">Compression</a>
            </span>
          </dt>
        </dl>
      </div>
      <p>
    There are a series of configuration tasks which you can perform when
    using the Btree access method.  They are described in the following sections.
</p>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="am_conf_bt_compare"></a>Btree comparison</h3>
            </div>
          </div>
        </div>
        <p>The Btree data structure is a sorted, balanced tree structure storing
associated key/data pairs.  By default, the sort order is lexicographical,
with shorter keys collating before longer keys.  The user can specify the
sort order for the Btree by using the <a href="../api_reference/C/dbset_bt_compare.html" class="olink">DB-&gt;set_bt_compare()</a> method.</p>
        <p>Sort routines are passed pointers to keys as arguments.  The keys are
represented as <a href="../api_reference/C/dbt.html" class="olink">DBT</a> structures.  The routine must return an integer
less than, equal to, or greater than zero if the first argument is
considered to be respectively less than, equal to, or greater than the
second argument.  The only fields that the routines may examine in the
<a href="../api_reference/C/dbt.html" class="olink">DBT</a> structures are <span class="bold"><strong>data</strong></span> and <span class="bold"><strong>size</strong></span> fields.</p>
        <p>An example routine that might be used to sort integer keys in the database
is as follows:</p>
        <a id="prog_am2"></a>
        <pre class="programlisting">
int
compare_int(DB *dbp, const DBT *a, const DBT *b)
    
{
    int ai, bi;
    /*
     * Returns:
     *    &lt; 0 if a &lt; b
     *    = 0 if a = b
     *    &gt; 0 if a &gt; b
     */
    memcpy(&amp;ai, a-&gt;data, sizeof(int));
    memcpy(&amp;bi, b-&gt;data, sizeof(int));
    return (ai - bi);
}
</pre>
        <p>Note that the data must first be copied into memory that is appropriately
aligned, as Berkeley DB does not guarantee any kind of alignment of the
underlying data, including for comparison routines.  When writing
comparison routines, remember that databases created on machines of
different architectures may have different integer byte orders, for which
your code may need to compensate.</p>
        <p>An example routine that might be used to sort keys based on the first
five bytes of the key (ignoring any subsequent bytes) is as follows:</p>
        <a id="prog_am3"></a>
        <pre class="programlisting">
int
compare_dbt(DB *dbp, const DBT *a, const DBT *b)
    
{
    int len;
    u_char *p1, *p2;

    /*
     * Returns:
     *    &lt; 0 if a &lt; b
     *    = 0 if a = b
     *    &gt; 0 if a &gt; b
     */
    for (p1 = a-&gt;data, p2 = b-&gt;data, len = 5; len--; ++p1, ++p2)
        if (*p1 != *p2)
            return ((long)*p1 - (long)*p2);
    return (0);
}
</pre>
        <p>All comparison functions must cause the keys in the database to be
well-ordered. The most important implication of being well-ordered is
that the key relations must be transitive, that is, if key A is less
than key B, and key B is less than key C, then the comparison routine
must also return that key A is less than key C.</p>
        <p>It is reasonable for a comparison function to not examine an entire key
in some applications, which implies partial keys may be specified to the
Berkeley DB interfaces.  When partial keys are specified to Berkeley DB, interfaces
which retrieve data items based on a user-specified key (for example,
<a href="../api_reference/C/dbget.html" class="olink">DB-&gt;get()</a> and <a href="../api_reference/C/dbcget.html" class="olink">DBC-&gt;get()</a> with the <a href="../api_reference/C/dbcget.html#dbcget_DB_SET" class="olink">DB_SET</a> flag), will
modify the user-specified key by returning the actual key stored in the
database.</p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="am_conf_bt_prefix"></a>Btree prefix comparison</h3>
            </div>
          </div>
        </div>
        <p>The Berkeley DB Btree implementation maximizes the number of keys that can be
stored on an internal page by storing only as many bytes of each key as
are necessary to distinguish it from adjacent keys.  The prefix
comparison routine is what determines this minimum number of bytes (that
is, the length of the unique prefix), that must be stored.  A prefix
comparison function for the Btree can be specified by calling
<a href="../api_reference/C/dbset_bt_prefix.html" class="olink">DB-&gt;set_bt_prefix()</a>.</p>
        <p>The prefix comparison routine must be compatible with the overall
comparison function of the Btree, since what distinguishes any two keys
depends entirely on the function used to compare them.  This means that
if a prefix comparison routine is specified by the application, a
compatible overall comparison routine must also have been specified.</p>
        <p>Prefix comparison routines are passed pointers to keys as arguments.
The keys are represented as <a href="../api_reference/C/dbt.html" class="olink">DBT</a> structures.  The only fields
the routines may examine in the <a href="../api_reference/C/dbt.html" class="olink">DBT</a> structures are <span class="bold"><strong>data</strong></span>
and <span class="bold"><strong>size</strong></span> fields.</p>
        <p>The prefix comparison function must return the number of bytes necessary
to distinguish the two keys.  If the keys are identical (equal and equal
in length), the length should be returned.  If the keys are equal up to
the smaller of the two lengths, then the length of the smaller key plus
1 should be returned.</p>
        <p>An example prefix comparison routine follows:</p>
        <a id="prog_am4"></a>
        <pre class="programlisting">
size_t
compare_prefix(DB *dbp, const DBT *a, const DBT *b)
   
{
    size_t cnt, len;
    u_int8_t *p1, *p2;

    cnt = 1;
    len = a-&gt;size &gt; b-&gt;size ? b-&gt;size : a-&gt;size;
    for (p1 =
        a-&gt;data, p2 = b-&gt;data; len--; ++p1, ++p2, ++cnt)
            if (*p1 != *p2)
                return (cnt);
    /*
     * They match up to the smaller of the two sizes.
     * Collate the longer after the shorter.
     */
    if (a-&gt;size &lt; b-&gt;size)
        return (a-&gt;size + 1);
    if (b-&gt;size &lt; a-&gt;size)
        return (b-&gt;size + 1);
    return (b-&gt;size);
}
</pre>
        <p>The usefulness of this functionality is data-dependent, but in some data
sets can produce significantly reduced tree sizes and faster search times.</p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="am_conf_bt_minkey"></a>Minimum keys per page</h3>
            </div>
          </div>
        </div>
        <p>The number of keys stored on each page affects the size of a Btree and
how it is maintained.  Therefore, it also affects the retrieval and search
performance of the tree.  For each Btree, Berkeley DB computes a maximum key
and data size.  This size is a function of the page size and the fact that
at least two key/data pairs must fit on any Btree page.  Whenever key or
data items exceed the calculated size, they are stored on overflow pages
instead of in the standard Btree leaf pages.</p>
        <p>Applications may use the <a href="../api_reference/C/dbset_bt_minkey.html" class="olink">DB-&gt;set_bt_minkey()</a> method to change the minimum
number of keys that must fit on a Btree page from two to another value.
Altering this value in turn alters the on-page maximum size, and can be
used to force key and data items which would normally be stored in the
Btree leaf pages onto overflow pages.</p>
        <p>Some data sets can benefit from this tuning.  For example, consider an
application using large page sizes, with a data set almost entirely
consisting of small key and data items, but with a few large items.  By
setting the minimum number of keys that must fit on a page, the
application can force the outsized items to be stored on overflow pages.
That in turn can potentially keep the tree more compact, that is, with
fewer internal levels to traverse during searches.</p>
        <p>The following calculation is similar to the one performed by the Btree
implementation.  (The <span class="bold"><strong>minimum_keys</strong></span> value is multiplied by 2
because each key/data pair requires 2 slots on a Btree page.)</p>
        <pre class="programlisting">maximum_size = page_size / (minimum_keys * 2)</pre>
        <p>Using this calculation, if the page size is 8KB and the default
<span class="bold"><strong>minimum_keys</strong></span> value of 2 is used, then any key or data items
larger than 2KB will be forced to an overflow page.  If an application
were to specify a <span class="bold"><strong>minimum_key</strong></span> value of 100, then any key or data
items larger than roughly 40 bytes would be forced to overflow pages.</p>
        <p>It is important to remember that accesses to overflow pages do not perform
as well as accesses to the standard Btree leaf pages, and so setting the
value incorrectly can result in overusing overflow pages and decreasing
the application's overall performance.</p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="am_conf_bt_recnum"></a>Retrieving Btree records by logical record number</h3>
            </div>
          </div>
        </div>
        <p>The Btree access method optionally supports retrieval by logical record
numbers.  To configure a Btree to support record numbers, call the
<a href="../api_reference/C/dbset_flags.html" class="olink">DB-&gt;set_flags()</a> method with the <a href="../api_reference/C/dbset_flags.html#dbset_flags_DB_RECNUM" class="olink">DB_RECNUM</a> flag.</p>
        <p>Configuring a Btree for record numbers should not be done lightly.
While often useful, it may significantly slow down the speed at which
items can be stored into the database, and can severely impact
application throughput.  Generally it should be avoided in trees with
a need for high write concurrency.</p>
        <p>To retrieve by record number, use the <a href="../api_reference/C/dbget.html#dbget_DB_SET_RECNO" class="olink">DB_SET_RECNO</a> flag to the
<a href="../api_reference/C/dbget.html" class="olink">DB-&gt;get()</a> and <a href="../api_reference/C/dbcget.html" class="olink">DBC-&gt;get()</a> methods.  The following is an example of
a routine that displays the data item for a Btree database created with
the <a href="../api_reference/C/dbset_flags.html#dbset_flags_DB_RECNUM" class="olink">DB_RECNUM</a> option.</p>
        <a id="prog_am5"></a>
        <pre class="programlisting">
int
rec_display(DB *dbp, db_recno_t recno)
    
{
    DBT key, data;
    int ret;

    memset(&amp;key, 0, sizeof(key));
    key.data = &amp;recno;
    key.size = sizeof(recno);
    memset(&amp;data, 0, sizeof(data));

    if ((ret = dbp-&gt;get(dbp, NULL, &amp;key, &amp;data, DB_SET_RECNO)) != 0)
        return (ret);
    printf("data for %lu: %.*s\n",
        (u_long)recno, (int)data.size, (char *)data.data);
    return (0);
}
</pre>
        <p>To determine a key's record number, use the <a href="../api_reference/C/dbcget.html#dbcget_DB_GET_RECNO" class="olink">DB_GET_RECNO</a> flag
to the <a href="../api_reference/C/dbcget.html" class="olink">DBC-&gt;get()</a> method.  The following is an example of a routine that
displays the record number associated with a specific key.</p>
        <a id="prog_am6"></a>
        <pre class="programlisting">
int
recno_display(DB *dbp, char *keyvalue)
    
{
    DBC *dbcp;
    DBT key, data;
    db_recno_t recno;
    int ret, t_ret;

    /* Acquire a cursor for the database. */
    if ((ret = dbp-&gt;cursor(dbp, NULL, &amp;dbcp, 0)) != 0) {
        dbp-&gt;err(dbp, ret, "DB-&gt;cursor");
        goto err;
    }

    /* Position the cursor. */
    memset(&amp;key, 0, sizeof(key));
    key.data = keyvalue;
    key.size = strlen(keyvalue);
    memset(&amp;data, 0, sizeof(data));
    if ((ret = dbcp-&gt;get(dbcp, &amp;key, &amp;data, DB_SET)) != 0) {
        dbp-&gt;err(dbp, ret, "DBC-&gt;get(DB_SET): %s", keyvalue);
        goto err;
    }

    /*
     * Request the record number, and store it into appropriately
     * sized and aligned local memory.
     */
    memset(&amp;data, 0, sizeof(data));
    data.data = &amp;recno;
    data.ulen = sizeof(recno);
    data.flags = DB_DBT_USERMEM;
    if ((ret = dbcp-&gt;get(dbcp, &amp;key, &amp;data, DB_GET_RECNO)) != 0) {
        dbp-&gt;err(dbp, ret, "DBC-&gt;get(DB_GET_RECNO)");
        goto err;
    }

    printf("key for requested key was %lu\n", (u_long)recno);

err:    /* Close the cursor. */
    if ((t_ret = dbcp-&gt;close(dbcp)) != 0) {
        if (ret == 0)
            ret = t_ret;
        dbp-&gt;err(dbp, ret, "DBC-&gt;close");
    }
    return (ret);
}
</pre>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="am_conf_bt_compress"></a>Compression</h3>
            </div>
          </div>
        </div>
        <p>
    The Btree access method supports the automatic compression of key/data
    pairs upon their insertion into the database.  The key/data pairs are
    decompressed before they are returned to the application, making an
    application's interaction with a compressed database identical to that
    for a non-compressed database.  To configure Berkeley DB for
    compression, call the <a href="../api_reference/C/dbset_bt_compress.html" class="olink">DB-&gt;set_bt_compress()</a> method and specify custom
    compression and decompression functions.  If <a href="../api_reference/C/dbset_bt_compress.html" class="olink">DB-&gt;set_bt_compress()</a> is
    called with NULL compression and decompression functions, Berkeley DB
    will use its default compression functions.
</p>
        <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
          <h3 class="title">Note</h3>
          <p>
        Compression only works with the Btree access method, and then only
        so long as your database is not configured for unsorted duplicates.
    </p>
        </div>
        <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
          <h3 class="title">Note</h3>
          <p>
	The default compression function is not guaranteed to reduce the 
	size of the on-disk database in every case.  It has been tested
	and shown to work well with English-language text.  Of course, in 
	order to determine if the default compression algorithm is beneficial
	for your application, it is important to test both the final size
	and the performance using a representative set of data and access
	patterns. 
    </p>
        </div>
        <p>
    The default compression function performs prefix compression on each
    key added to the database.  This means that, for a key
    <span class="emphasis"><em>n</em></span> bytes in length, the first
    <span class="emphasis"><em>i</em></span> bytes that match the first
    <span class="emphasis"><em>i</em></span> bytes of the previous key exactly are omitted
    and only the final <span class="emphasis"><em>n-i</em></span> bytes are stored in the
    database.  If the bytes of key being stored match the bytes of the
    previous key exactly, then the same prefix compression algorithm is
    applied to the data value being stored.  To use Berkeley DB's default
    compression behavior, both the default compression and decompression
    functions must be used.
</p>
        <p>
    For example, to configure your database for default compression:
</p>
        <a id="prog_am7"></a>
        <pre class="programlisting">
    DB *dbp = NULL;
    DB_ENV *envp = NULL;
     u_int32_t db_flags; 
    const char *file_name = "mydb.db"; 
    int ret;

...
    
    /* Skipping environment open to shorten this example */
    /* Initialize the DB handle */
    ret = db_create(&amp;dbp, envp, 0);
    if (ret != 0) {
        fprintf(stderr, "%s\n", db_strerror(ret));
        return (EXIT_FAILURE);
    }

    /* Turn on default data compression */
    dbp-&gt;set_bt_compress(dbp, NULL, NULL);

    /* Now open the database */
    db_flags = DB_CREATE;       /* Allow database creation */

    ret = dbp-&gt;open(dbp,        /* Pointer to the database */
                    NULL,       /* Txn pointer */
                    file_name,  /* File name */
                    NULL,       /* Logical db name */
                    DB_BTREE,   /* Database type (using btree) */
                    db_flags,   /* Open flags */
                    0);         /* File mode. Using defaults */
    if (ret != 0) {
        dbp-&gt;err(dbp, ret, "Database '%s' open failed",
            file_name);
        return (EXIT_FAILURE);
    }</pre>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="am_conf_bt_custom_compress"></a>Custom compression</h4>
              </div>
            </div>
          </div>
          <p>
    An application wishing to perform its own compression may supply a
    compression and decompression function which will be called instead of
    Berkeley DB's default functions.  The compression function is
    passed five <a href="../api_reference/C/dbt.html" class="olink">DBT</a> structures: 
</p>
          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p>
                The key and data immediately preceeding the key/data pair
                that is being stored.
            </p>
              </li>
              <li>
                <p>
                The key and data being stored in the tree.
            </p>
              </li>
              <li>
                <p>
                The buffer where the compressed data should be written. 
            </p>
              </li>
            </ul>
          </div>
          <p>
        The total size of the buffer used to store the compressed data is
        identified in the <a href="../api_reference/C/dbt.html" class="olink">DBT</a>'s <code class="literal">ulen</code> field.  If the
        compressed data cannot fit in the buffer, the compression function
        should store the amount of space needed in <a href="../api_reference/C/dbt.html" class="olink">DBT</a>'s
        <code class="literal">size</code> field and then return 
        <code class="literal">DB_BUFFER_SMALL</code>. Berkeley DB will subsequently
        re-call the compression function with the required amount of space
        allocated in the compression data buffer.
    </p>
          <p>
        Multiple compressed key/data pairs will likely be written to the
        same buffer and the compression function should take steps to
        ensure it does not overwrite data.  
    </p>
          <p>
        For example, the following code fragments illustrate the use of a custom
        compression routine. This code is actually a much simplified
        example of the default compression provided by Berkeley DB. It does
        simple prefix compression on the key part of the data.
    </p>
          <a id="prog_am8"></a>
          <pre class="programlisting">
    int compress(DB *dbp, const DBT *prevKey, const DBT *prevData, 
        const DBT *key, const DBT *data, DBT *dest)
{
    u_int8_t *dest_data_ptr;
    const u_int8_t *key_data, *prevKey_data;
    size_t len, prefix, suffix;

    key_data = (const u_int8_t*)key-&gt;data;
    prevKey_data = (const u_int8_t*)prevKey-&gt;data;
    len = key-&gt;size &gt; prevKey-&gt;size ? prevKey-&gt;size : key-&gt;size;
    for (; len-- &amp;&amp; *key_data == *prevKey_data; ++key_data, 
                                                ++prevKey_data)
        continue;

    prefix = (size_t)(key_data - (u_int8_t*)key-&gt;data);
    suffix = key-&gt;size - prefix;

    /* Check that we have enough space in dest */
    dest-&gt;size = (u_int32_t)(__db_compress_count_int(prefix) +
        __db_compress_count_int(suffix) +
        __db_compress_count_int(data-&gt;size) + suffix + data-&gt;size);
    if (dest-&gt;size &gt; dest-&gt;ulen)
        return (DB_BUFFER_SMALL);

    /* prefix length */
    dest_data_ptr = (u_int8_t*)dest-&gt;data;
    dest_data_ptr += __db_compress_int(dest_data_ptr, prefix);

    /* suffix length */
    dest_data_ptr += __db_compress_int(dest_data_ptr, suffix);

    /* data length */
    dest_data_ptr += __db_compress_int(dest_data_ptr, data-&gt;size);

    /* suffix */
    memcpy(dest_data_ptr, key_data, suffix);
    dest_data_ptr += suffix;

    /* data */
    memcpy(dest_data_ptr, data-&gt;data, data-&gt;size);

    return (0);
} </pre>
          <p>
        The corresponding decompression function is likewise passed five <a href="../api_reference/C/dbt.html" class="olink">DBT</a> structures: 
    </p>
          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p>
                The key and data <a href="../api_reference/C/dbt.html" class="olink">DBT</a>s immediately preceding the
                decompressed key and data.
            </p>
              </li>
              <li>
                <p>
                The compressed data from the database.
            </p>
              </li>
              <li>
                <p>
                One to store the decompressed key and another one for the
                decompressed data.
            </p>
              </li>
            </ul>
          </div>
          <p>
        Because the compression of <code class="literal">record X</code> relies upon
        <code class="literal">record X-1</code>, the decompression function can be
        called repeatedly to linearally decompress a set of records stored
        in the compressed buffer.  
    </p>
          <p>
        The total size of the buffer available to store the decompressed data is
        identified in the destination <a href="../api_reference/C/dbt.html" class="olink">DBT</a>'s <code class="literal">ulen</code> field.  If the
        decompressed data cannot fit in the buffer, the decompression function
        should store the amount of space needed in the destination <a href="../api_reference/C/dbt.html" class="olink">DBT</a>'s
        <code class="literal">size</code> field and then return 
        <code class="literal">DB_BUFFER_SMALL</code>. Berkeley DB will subsequently
        re-call the decompression function with the required amount of space
        allocated in the decompression data buffer.
    </p>
          <p>
    For example, the decompression routine that corresponds to the
    example compression routine provided above is:
</p>
          <a id="prog_am9"></a>
          <pre class="programlisting">int decompress(DB *dbp, const DBT *prevKey, const DBT *prevData, 
    DBT *compressed, DBT *destKey, DBT *destData)
{
    u_int8_t *comp_data, *dest_data;
    u_int32_t prefix, suffix, size;

    /* Unmarshal prefix, suffix and data length */
    comp_data = (u_int8_t*)compressed-&gt;data;
    size = __db_decompress_count_int(comp_data);
    if (size &gt; compressed-&gt;size)
        return (EINVAL);
    comp_data += __db_decompress_int32(comp_data, &amp;prefix);

    size += __db_decompress_count_int(comp_data);
    if (size &gt; compressed-&gt;size)
        return (EINVAL);
    comp_data += __db_decompress_int32(comp_data, &amp;suffix);

    size += __db_decompress_count_int(comp_data);
    if (size &gt; compressed-&gt;size)
        return (EINVAL);
    comp_data += __db_decompress_int32(comp_data, &amp;destData-&gt;size);

    /* Check destination lengths */
    destKey-&gt;size = prefix + suffix;
    if (destKey-&gt;size &gt; destKey-&gt;ulen || 
            destData-&gt;size &gt; destData-&gt;ulen)
        return (DB_BUFFER_SMALL);

    /* Write the prefix */
    if (prefix &gt; prevKey-&gt;size)
        return (EINVAL);
    dest_data = (u_int8_t*)destKey-&gt;data;
    memcpy(dest_data, prevKey-&gt;data, prefix);
    dest_data += prefix;

    /* Write the suffix */
    size += suffix;
    if (size &gt; compressed-&gt;size)
        return (EINVAL);
    memcpy(dest_data, comp_data, suffix);
    comp_data += suffix;

    /* Write the data */
    size += destData-&gt;size;
    if (size &gt; compressed-&gt;size)
        return (EINVAL);
    memcpy(destData-&gt;data, comp_data, destData-&gt;size);
    comp_data += destData-&gt;size;

    /* Return bytes read */
    compressed-&gt;size = 
        (u_int32_t)(comp_data - (u_int8_t*)compressed-&gt;data);
    return (0);
} </pre>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp50856856"></a>Programmer Notes</h4>
              </div>
            </div>
          </div>
          <p>
        As you use compression with your databases, be aware of the
        following:
    </p>
          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p>
                Compression works by placing key/data pairs from a single
                database page into a single block of compressed data. This is true
                whether you use DB's default compression, or you write
                your own compression. Because all of key/data data is
                placed in a single block of memory, you cannot decompress
                data unless you have decompressed everything that came
                before it in the block. That is, you cannot decompress item
                <span class="emphasis"><em>n</em></span> in the data block, unless you also
                decompress items <span class="emphasis"><em>0</em></span> through
                <span class="emphasis"><em>n-1</em></span>.
            </p>
              </li>
              <li>
                <p>
                If you increase the minimum number of key/data pairs placed
                on a Btree leaf page (using <a href="../api_reference/C/dbset_bt_minkey.html" class="olink">DB-&gt;set_bt_minkey()</a>), you will
                decrease your seek times on a compressed database. However,
                this will also decrease the effectiveness of the
                compression.
            </p>
              </li>
              <li>
                <p>
                Compressed databases are fastest if bulk load is used to
                add data to them. See 
                <a class="xref" href="am_misc_bulk.html" title="Retrieving and updating records in bulk">Retrieving and updating records in bulk</a>
                for information on using bulk load.
            </p>
              </li>
            </ul>
          </div>
        </div>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="general_am_conf.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="am_conf.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="hash_conf.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">General access method configuration </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Hash access method specific configuration</td>
        </tr>
      </table>
    </div>
  </body>
</html>