Sindbad~EG File Manager
<?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>Chapter 14. External Files</title>
<link rel="stylesheet" href="apiReference.css" type="text/css" />
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
<link rel="start" href="index.html" title="Berkeley DB C++ API Reference" />
<link rel="up" href="index.html" title="Berkeley DB C++ API Reference" />
<link rel="prev" href="txnset_timeout.html" title="DbTxn::set_timeout()" />
<link rel="next" href="get_blob_dir.html" title="Db::get_ext_file_dir()" />
</head>
<body>
<div xmlns="" class="navheader">
<div class="libver">
<p>Library Version 18.1.40</p>
</div>
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Chapter 14.
External Files
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="txnset_timeout.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="get_blob_dir.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="chapter" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="blob"></a>Chapter 14.
External Files
</h2>
</div>
</div>
</div>
<p>
External file support is designed for efficient
storage of large objects. An object is considered to be large
if it is more than a third of the size of a page. Without external
file support, large objects must be broken up into smaller pieces,
and then reassembled and/or disassembled every time the record
is read or updated. Berkeley DB external file support avoids this
assembly/disassembly process by storing the large object in a
special directory set aside for the purpose. The data itself
is not kept in the database, nor is it placed into the
in-memory cache.
</p>
<p>
External files can only be stored using the data portion of a
key/data pair. They are supported only for Btree, Hash, and Heap
databases, and only so long as the database is not configured
for duplicate records, or duplicate
sorted records. In addition, the Dbt that you use to
access the external file data cannot be configured as a partial
Dbt if you want to access the data using the external
file's streaming interface (introduced below).
</p>
<p>
Note that if the environment is transactionally-protected, then
all access to the external file is also transactionally protected.
</p>
<p>
External files cannot be used with in-memory-only databases.
</p>
<p>
In order to use Berkeley DB's external file support, you must set
the external file threshold to a non-zero positive value. (The
default value is <code class="literal">0</code>, which means that external
files are not enabled). You set the external file threshold using
either <a class="xref" href="set_blob_threshold.html" title="Db::set_ext_file_threshold()">
<span>Db::set_ext_file_threshold()</span>
</a> or <a class="xref" href="envset_blob_threshold.html" title="DbEnv::set_ext_file_threshold()">
<span>DbEnv::set_ext_file_threshold()</span>
</a>.
</p>
<p>
Once external files are enabled, there are two ways to create an
external file record:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
Configure the Dbt used to access the external file
data (that is, the Dbt used for the data portion of
the record) with the
<a class="link" href="dbt.html#dbt_DB_DBT_BLOB">DB_DBT_EXT_FILE</a>
flag. This causes the data to be stored as an external file
regardless of its size, so long as the database
otherwise supports external files.
</p>
</li>
<li>
<p>
Alternatively, creating a data item with a size greater
than the external file threshold will cause that data item
to be stored as an external file. Of course, for this
method to work, the external file threshold must be greater
than <code class="literal">0</code>.
</p>
</li>
</ul>
</div>
<p>
external files may be accessed in the same way as other Dbt
data, so long as the data itself will fit into memory. More
likely, you will find it necessary to use the external file
streaming API to read and write external file data. You open an
external file stream using the <a class="xref" href="dbstream.html" title="Dbc::db_stream()">
<span>Dbc::db_stream()</span>
</a> method, close it with
the <a class="xref" href="dbstream_close.html" title="DbStream::close()">
<span>DbStream::close()</span>
</a> method, write to it using the the
<a class="xref" href="dbstream_write.html" title="DbStream::write()">
<span>DbStream::write()</span>
</a> method, and read it using the <a class="xref" href="dbstream_read.html" title="DbStream::read()">
<span>DbStream::read()</span>
</a>
method.
</p>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="bloblist"></a>External Files and Related Methods</h2>
</div>
</div>
</div>
<div class="navtable">
<table border="1" width="80%">
<thead>
<tr>
<th>External File Operations</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<a class="xref" href="dbstream.html" title="Dbc::db_stream()">
<span>Dbc::db_stream()</span>
</a>
</td>
<td>Create an external file stream</td>
</tr>
<tr>
<td>
<a class="xref" href="dbstream_close.html" title="DbStream::close()">
<span>DbStream::close()</span>
</a>
</td>
<td>Close an external file stream</td>
</tr>
<tr>
<td>
<a class="xref" href="dbstream_read.html" title="DbStream::read()">
<span>DbStream::read()</span>
</a>
</td>
<td>Read an external file stream</td>
</tr>
<tr>
<td>
<a class="xref" href="dbstream_size.html" title="DbStream::size()">
<span>DbStream::size()</span>
</a>
</td>
<td>Returns the size of an external file</td>
</tr>
<tr>
<td>
<a class="xref" href="dbstream_write.html" title="DbStream::write()">
<span>DbStream::write()</span>
</a>
</td>
<td>Write an external file stream</td>
</tr>
<tr>
<td colspan="2">
<span class="bold">
<strong>External File Configuration</strong>
</span>
</td>
</tr>
<tr>
<td><a class="xref" href="set_blob_dir.html" title="Db::set_ext_file_dir()">
<span>Db::set_ext_file_dir()</span>
</a>, <a class="xref" href="get_blob_dir.html" title="Db::get_ext_file_dir()">
<span>Db::get_ext_file_dir()</span>
</a></td>
<td>Sets/gets the location where external file data is stored</td>
</tr>
<tr>
<td><a class="xref" href="set_blob_threshold.html" title="Db::set_ext_file_threshold()">
<span>Db::set_ext_file_threshold()</span>
</a>, <a class="xref" href="get_blob_threshold.html" title="Db::get_ext_file_threshold()">
<span>Db::get_ext_file_threshold()</span>
</a></td>
<td>Sets/gets the size when data records are stored as external files</td>
</tr>
<tr>
<td><a class="xref" href="envset_blob_dir.html" title="DbEnv::set_ext_file_dir()">
<span>DbEnv::set_ext_file_dir()</span>
</a>, <a class="xref" href="envget_blob_dir.html" title="DbEnv::get_ext_file_dir()">
<span>DbEnv::get_ext_file_dir()</span>
</a></td>
<td>Sets/gets the location where external file data is stored</td>
</tr>
<tr>
<td><a class="xref" href="envset_blob_threshold.html" title="DbEnv::set_ext_file_threshold()">
<span>DbEnv::set_ext_file_threshold()</span>
</a>, <a class="xref" href="envget_blob_threshold.html" title="DbEnv::get_ext_file_threshold()">
<span>DbEnv::get_ext_file_threshold()</span>
</a></td>
<td>Sets/gets the default size for the environment when external files are used</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="txnset_timeout.html">Prev</a> </td>
<td width="20%" align="center"> </td>
<td width="40%" align="right"> <a accesskey="n" href="get_blob_dir.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
<span>DbTxn::set_timeout()</span>
</td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top">
<span>Db::get_ext_file_dir()</span>
</td>
</tr>
</table>
</div>
</body>
</html>
Sindbad File Manager Version 1.0, Coded By Sindbad EG ~ The Terrorists