diff options
Diffstat (limited to 'docs/programmer_reference/am_opensub.html')
| -rw-r--r-- | docs/programmer_reference/am_opensub.html | 174 |
1 files changed, 103 insertions, 71 deletions
diff --git a/docs/programmer_reference/am_opensub.html b/docs/programmer_reference/am_opensub.html index e071976d..0fb6d8be 100644 --- a/docs/programmer_reference/am_opensub.html +++ b/docs/programmer_reference/am_opensub.html @@ -14,17 +14,16 @@ <body> <div xmlns="" class="navheader"> <div class="libver"> - <p>Library Version 11.2.5.3</p> + <p>Library Version 12.1.6.1</p> </div> <table width="100%" summary="Navigation header"> <tr> - <th colspan="3" align="center">Opening multiple databases in a single file</th> + <th colspan="3" align="center">Opening multiple databases in a + single file</th> </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="am.html">Prev</a> </td> - <th width="60%" align="center">Chapter 3. - Access Method Operations - </th> + <th width="60%" align="center">Chapter 3. Access Method Operations </th> <td width="20%" align="right"> <a accesskey="n" href="am_partition.html">Next</a></td> </tr> </table> @@ -34,7 +33,8 @@ <div class="titlepage"> <div> <div> - <h2 class="title" style="clear: both"><a id="am_opensub"></a>Opening multiple databases in a single file</h2> + <h2 class="title" style="clear: both"><a id="am_opensub"></a>Opening multiple databases in a + single file</h2> </div> </div> </div> @@ -42,103 +42,137 @@ <dl> <dt> <span class="sect2"> - <a href="am_opensub.html#idp724392">Configuring databases sharing a file</a> + <a href="am_opensub.html#idm1925008">Configuring databases sharing a file</a> </span> </dt> <dt> <span class="sect2"> - <a href="am_opensub.html#idp768720">Caching databases sharing a file</a> + <a href="am_opensub.html#idm148416">Caching databases sharing a file</a> </span> </dt> <dt> <span class="sect2"> - <a href="am_opensub.html#idp769416">Locking in databases based on sharing a file</a> + <a href="am_opensub.html#idm548184">Locking in databases based on sharing a file</a> </span> </dt> </dl> </div> - <p>Applications may create multiple databases within a single physical -file. This is useful when the databases are both numerous and -reasonably small, in order to avoid creating a large number of -underlying files, or when it is desirable to include secondary index -databases in the same file as the primary index database. Putting -multiple databases in a single physical file is an administrative -convenience and unlikely to affect database performance.</p> - <p>To open or create a file that will include more than a single database, -specify a database name when calling the <a href="../api_reference/C/dbopen.html" class="olink">DB->open()</a> method.</p> - <p>Physical files do not need to be comprised of a single type of database, -and databases in a file may be of any mixture of types, except for Queue and Heap -databases. Queue and Heap databases must be created one per file and cannot -share a file with any other database type. There is no limit on the -number of databases that may be created in a single file other than the -standard Berkeley DB file size and disk space limitations.</p> - <p>It is an error to attempt to open a second database in a file that was -not initially created using a database name, that is, the file must -initially be specified as capable of containing multiple databases for a -second database to be created in it.</p> - <p>It is not an error to open a file that contains multiple databases -without specifying a database name, however the database type should be -specified as DB_UNKNOWN and the database must be opened read-only. The -handle that is returned from such a call is a handle on a database whose -key values are the names of the databases stored in the database file -and whose data values are opaque objects. No keys or data values may be -modified or stored using this database handle.</p> + <p> + Applications may create multiple databases within a single + physical file. This is useful when the databases are both + numerous and reasonably small, in order to avoid creating a + large number of underlying files, or when it is desirable to + include secondary index databases in the same file as the + primary index database. Putting multiple databases in a single + physical file is an administrative convenience and unlikely to + affect database performance. + </p> + <p> + To open or create a file that will include more than a + single database, specify a database name when calling the + <a href="../api_reference/C/dbopen.html" class="olink">DB->open()</a> method. + </p> + <p> + Physical files do not need to be comprised of a single type + of database, and databases in a file may be of any mixture of + types, except for Queue and Heap databases. Queue and Heap + databases must be created one per file and cannot share a file + with any other database type. There is no limit on the number + of databases that may be created in a single file other than + the standard Berkeley DB file size and disk space + limitations. + </p> + <p> + It is an error to attempt to open a second database in a + file that was not initially created using a database name, + that is, the file must initially be specified as capable of + containing multiple databases for a second database to be + created in it. + </p> + <p> + It is not an error to open a file that contains multiple + databases without specifying a database name, however the + database type should be specified as DB_UNKNOWN and the + database must be opened read-only. The handle that is returned + from such a call is a handle on a database whose key values + are the names of the databases stored in the database file and + whose data values are opaque objects. No keys or data values + may be modified or stored using this database handle. + </p> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> - <h3 class="title"><a id="idp724392"></a>Configuring databases sharing a file</h3> + <h3 class="title"><a id="idm1925008"></a>Configuring databases sharing a file</h3> </div> </div> </div> - <p>There are four pieces of configuration information which must be -specified consistently for all databases in a file, rather than -differing on a per-database basis. They are: byte order, checksum and -encryption behavior, and page size. When creating additional databases -in a file, any of these configuration values specified must be -consistent with the existing databases in the file or an error will be -returned.</p> + <p> + There are four pieces of configuration information which + must be specified consistently for all databases in a + file, rather than differing on a per-database basis. They + are: byte order, checksum and encryption behavior, and + page size. When creating additional databases in a file, + any of these configuration values specified must be + consistent with the existing databases in the file or an + error will be returned. + </p> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> - <h3 class="title"><a id="idp768720"></a>Caching databases sharing a file</h3> + <h3 class="title"><a id="idm148416"></a>Caching databases sharing a file</h3> </div> </div> </div> - <p>When storing multiple databases in a single physical file rather than -in separate files, if any of the databases in a file is opened for -update, all of the databases in the file must share a memory pool. In -other words, they must be opened in the same database environment. This -is so per-physical-file information common between the two databases is -updated correctly.</p> + <p> + When storing multiple databases in a single physical + file rather than in separate files, if any of the + databases in a file is opened for update, all of the + databases in the file must share a memory pool. In other + words, they must be opened in the same database + environment. This is so per-physical-file information + common between the two databases is updated + correctly. + </p> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> - <h3 class="title"><a id="idp769416"></a>Locking in databases based on sharing a file</h3> + <h3 class="title"><a id="idm548184"></a>Locking in databases based on sharing a file</h3> </div> </div> </div> - <p>If databases are in separate files (and access to each separate database -is single-threaded), there is no reason to perform any locking of any -kind, and the two databases may be read and written simultaneously. -Further, there would be no requirement to create a shared database -environment in which to open those two databases.</p> - <p>However, since multiple databases in a file exist in a single physical -file, opening two databases in the same file simultaneously requires -locking be enabled, unless all of the databases are read-only. As the -locks for the two databases can only conflict during page allocation, -this additional locking is unlikely to affect performance. The -exception is when Berkeley DB Concurrent Data Store is configured; a single lock is used for all -databases in the file when Berkeley DB Concurrent Data Store is configured, and a write to one -database will block all accesses to all databases.</p> - <p>In summary, programmers writing applications that open multiple -databases in a single file will almost certainly need to create a shared -database environment in the application as well. For more information -on database environments, see <a class="xref" href="env.html#env_intro" title="Database environment introduction">Database environment introduction</a></p> + <p> + If databases are in separate files (and access to each + separate database is single-threaded), there is no reason + to perform any locking of any kind, and the two databases + may be read and written simultaneously. Further, there + would be no requirement to create a shared database + environment in which to open those two databases. + </p> + <p> + However, since multiple databases in a file exist in a + single physical file, opening two databases in the same + file simultaneously requires locking be enabled, unless + all of the databases are read-only. As the locks for the + two databases can only conflict during page allocation, + this additional locking is unlikely to affect performance. + The exception is when Berkeley DB Concurrent Data Store is + configured; a single lock is used for all databases in the + file when Berkeley DB Concurrent Data Store is configured, + and a write to one database will block all accesses to all + databases. + </p> + <p> + In summary, programmers writing applications that open + multiple databases in a single file will almost certainly + need to create a shared database environment in the + application as well. For more information on database + environments, see <a class="xref" href="env.html#env_intro" title="Database environment introduction">Database environment introduction</a> + </p> </div> </div> <div class="navfooter"> @@ -152,9 +186,7 @@ on database environments, see <a class="xref" href="env.html#env_intro" title="D <td width="40%" align="right"> <a accesskey="n" href="am_partition.html">Next</a></td> </tr> <tr> - <td width="40%" align="left" valign="top">Chapter 3. - Access Method Operations - </td> + <td width="40%" align="left" valign="top">Chapter 3. Access Method Operations </td> <td width="20%" align="center"> <a accesskey="h" href="index.html">Home</a> </td> |