Edit File - File Manager

Edit File: memp_fget.html

<html>
<head>
<title>Berkeley DB: DbMpoolFile::get</title>
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
</head>
<body bgcolor=white>
<table width="100%"><tr valign=top>
<td>
DbMpoolFile::get
</td>
<td align=right>
<a href="../../db4-devel-4.7.25/api_cxx/api_core.html"><img src="../../db4-devel-4.7.25/images/api.gif" alt="API"></a>
<a href="../../db4-devel-4.7.25/ref/toc.html"><img src="../../db4-devel-4.7.25/images/ref.gif" alt="Ref"></a></td>
</tr></table>
<hr size=1 noshade>
<tt>
<pre>
#include &lt;db_cxx.h&gt;

int
DbMpoolFile::get(db_pgno_t *pgnoaddr,
 DbTxn *txnid, u_int32_t flags, void **pagep);
</pre>
<hr size=1 noshade>
Description: DbMpoolFile::get
The DbMpoolFile::get method returns pages from the cache.
All pages returned by DbMpoolFile::get will be retained (that is,
pinned), in the pool until a subsequent call to
<a href="../../db4-devel-4.7.25/api_cxx/memp_fput.html">DbMpoolFile::put</a>.
The returned page is size_t type aligned.
Fully or partially created pages have all their bytes set to a nul byte,
unless the <a href="../../db4-devel-4.7.25/api_cxx/memp_set_clear_len.html">DbMpoolFile::set_clear_len</a> method was called to specify other
behavior before the file was opened.
<a name="2"></a>
The DbMpoolFile::get method
will either return DB_PAGE_NOTFOUND or
throw an exception that encapsulates DB_PAGE_NOTFOUND if the requested page does not exist and DB_MPOOL_CREATE was
not set.
Unless otherwise specified, the DbMpoolFile::get method
either returns a non-zero error value
or throws an exception that encapsulates a non-zero error value on
failure, and returns 0 on success.

Parameters 
 flags<ul compact><li>The flags parameter must be set to 0 or by bitwise inclusively OR'ing together one
or more of the following values:
 
<a name="DB_MPOOL_CREATE">DB_MPOOL_CREATE</a><ul compact><li>If the specified page does not exist, create it. In this case, the
<a href="memp_register.html#pgin">pgin</a> method, if specified, is
called.</ul>
<a name="DB_MPOOL_DIRTY">DB_MPOOL_DIRTY</a><ul compact><li>The page will be modified and must be written to the source file before
being evicted from the pool. For files open with the
<a href="../../db4-devel-4.7.25/api_cxx/db_open.html#DB_MULTIVERSION">DB_MULTIVERSION</a> flag set, a new copy of the page will be made
if this is the first time the specified transaction is modifying it.</ul>
<a name="DB_MPOOL_EDIT">DB_MPOOL_EDIT</a><ul compact><li>The page will be modified and must be written to the source file before
being evicted from the pool. No copy of the page will be made, regardless
of the <a href="../../db4-devel-4.7.25/api_cxx/db_open.html#DB_MULTIVERSION">DB_MULTIVERSION</a> setting. This flag is only intended for
use in situations where a transaction handle is not available, such as during
aborts or recovery.</ul>
<a name="DB_MPOOL_LAST">DB_MPOOL_LAST</a><ul compact><li>Return the last page of the source file, and copy its page number into
the memory location to which pgnoaddr refers.</ul>
<a name="DB_MPOOL_NEW">DB_MPOOL_NEW</a><ul compact><li>Create a new page in the file, and copy its page number into the memory
location to which pgnoaddr refers. In this case, the
<a href="memp_register.html#pgin">pgin</a> method, if specified, is
not called.</ul>
 
The DB_MPOOL_CREATE, DB_MPOOL_LAST, and
DB_MPOOL_NEW flags are mutually exclusive.</ul>
 pagep<ul compact><li>The pagep parameter references memory into which
a pointer to the returned page is copied.</ul> 
 pgnoaddr<ul compact><li>If the flags parameter is set to DB_MPOOL_LAST or
DB_MPOOL_NEW, the page number of the created page is copied
into the memory location to which the pgnoaddr parameter
refers. Otherwise, the pgnoaddr parameter is the page to
create or retrieve.
Page numbers begin at 0; that is, the first page in the file is page
number 0, not page number 1.</ul>
 txnid<ul compact><li>If the operation is part of an application-specified
transaction, the txnid parameter is a transaction handle
returned from <a href="../../db4-devel-4.7.25/api_cxx/txn_begin.html">DbEnv::txn_begin</a>; otherwise NULL. A transaction is
required if the file is open for multiversion concurrency control by
passing <a href="../../db4-devel-4.7.25/api_cxx/db_open.html#DB_MULTIVERSION">DB_MULTIVERSION</a> to <a href="../../db4-devel-4.7.25/api_cxx/memp_fopen.html">DbMpoolFile::open</a> and the
DB_MPOOL_DIRTY, DB_MPOOL_CREATE or
DB_MPOOL_NEW flags were specified. Otherwise it is ignored.</ul>
 
 Errors
The DbMpoolFile::get method
may fail and throw
<a href="../../db4-devel-4.7.25/api_cxx/except_class.html">DbException</a>,
encapsulating one of the following non-zero errors, or return one of
the following non-zero errors:
 
EACCES<ul compact><li>The DB_MPOOL_DIRTY or DB_MPOOL_EDIT flag was set and
the source file was not opened for writing.</ul>
 
 
EAGAIN<ul compact><li>The page reference count has overflowed. (This should never happen
unless there is a bug in the application.)</ul>
 
 
EINVAL<ul compact><li>If the DB_MPOOL_NEW flag was set, and the source file was not
opened for writing;
more than one of DB_MPOOL_CREATE, DB_MPOOL_LAST, and
DB_MPOOL_NEW was set.; or if an
invalid flag value or parameter was specified.</ul>
 
 
DB_LOCK_DEADLOCK<ul compact><li>For transactions configured with <a href="../../db4-devel-4.7.25/api_cxx/txn_begin.html#DB_TXN_SNAPSHOT">DB_TXN_SNAPSHOT</a>, the page has
been modified since the transaction began.</ul>
 
If the cache is full, and no more pages will fit in the pool, the DbMpoolFile::get method will fail and
either return ENOMEM or
throw a DbMemoryException.
<hr size=1 noshade>
 Class
<a href="../../db4-devel-4.7.25/api_cxx/env_class.html">DbEnv</a>, <a href="../../db4-devel-4.7.25/api_cxx/mempfile_class.html">DbMpoolFile</a>
 See Also
<a href="../../db4-devel-4.7.25/api_cxx/memp_list.html">Memory Pools and Related Methods</a>
</tt>
<table width="100%"><tr><td> </td><td align=right>
<a href="../../db4-devel-4.7.25/api_cxx/api_core.html"><img src="../../db4-devel-4.7.25/images/api.gif" alt="API"></a><a href="../../db4-devel-4.7.25/ref/toc.html"><img src="../../db4-devel-4.7.25/images/ref.gif" alt="Ref"></a>
</td></tr></table>
Copyright (c) 1996,2008 Oracle. All rights reserved.
</body>
</html>

Back to File Manager