<!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/xhtml;charset=UTF-8"/>
<title>libsq3: sq3::database Class Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.6.2-20100208 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li class="current"><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div class="tabs">
<ul>
<li><a href="annotated.html"><span>Class List</span></a></li>
<li><a href="classes.html"><span>Class Index</span></a></li>
<li><a href="hierarchy.html"><span>Class Hierarchy</span></a></li>
<li><a href="functions.html"><span>Class Members</span></a></li>
</ul>
</div>
<div class="navpath"><a class="el" href="namespacesq3.html">sq3</a>::<a class="el" href="classsq3_1_1database.html">database</a>
</div>
</div>
<div class="contents">
<h1>sq3::database Class Reference</h1><!-- doxytag: class="sq3::database" -->
<p>Encapsulates a connection to an sqlite database.
<a href="#_details">More...</a></p>
<p><code>#include <<a class="el" href="sq3_8hpp_source.html">sq3.hpp</a>></code></p>
<div class="dynheader">
Inheritance diagram for sq3::database:</div>
<div class="dynsection">
<div class="center">
<img src="classsq3_1_1database.png" usemap="#sq3::database_map" alt=""/>
<map id="sq3::database_map" name="sq3::database_map">
<area href="classsq3_1_1log__db.html" alt="sq3::log_db" shape="rect" coords="0,56,100,80"/>
<area href="classsq3_1_1settings__db.html" alt="sq3::settings_db" shape="rect" coords="110,56,210,80"/>
</map>
</div>
</div>
<p><a href="classsq3_1_1database-members.html">List of all members.</a></p>
<table border="0" cellpadding="0" cellspacing="0">
<tr><td colspan="2"><h2>Public Member Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">sqlite3 * </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#a674d66007f7cf0fe2f68233593526ecb">handle</a> () const </td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">The low-level handle to the sqlite db. <a href="#a674d66007f7cf0fe2f68233593526ecb"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#a031f52c894718d806d3d09696901dcca">database</a> ()</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Creates an unopened database. <a href="#a031f52c894718d806d3d09696901dcca"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#acf216ebb32313e51215468aec2ef0952">take_handle</a> (sqlite3 *dbh, std::string const &name="")</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">dbh is assumed to be an opened, valid db handle. <a href="#acf216ebb32313e51215468aec2ef0952"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">sqlite3 * </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#a96e7f35f86397c1f82325ec902d66600">take_handle</a> ()</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Transfers ownership of this-><a class="el" href="classsq3_1_1database.html#a674d66007f7cf0fe2f68233593526ecb" title="The low-level handle to the sqlite db.">handle()</a> to the caller. <a href="#a96e7f35f86397c1f82325ec902d66600"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#a5dca436b8be0c07023e8347bb5137a80">database</a> (std::string const &filename)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Opens/creates the given db file. <a href="#a5dca436b8be0c07023e8347bb5137a80"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="a23fa7ca868f48e4de39c0f0f55cd2c9c"></a><!-- doxytag: member="sq3::database::~database" ref="a23fa7ca868f48e4de39c0f0f55cd2c9c" args="()" -->
virtual </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#a23fa7ca868f48e4de39c0f0f55cd2c9c">~database</a> ()</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Closes this db. <br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#af3b6b07c453a2ce5eaf9072e9cbe1f84">is_open</a> () const </td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Returns true if this db is opened. <a href="#af3b6b07c453a2ce5eaf9072e9cbe1f84"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="a70b7775e8ec6b930cd1df88c1d691d6a"></a><!-- doxytag: member="sq3::database::name" ref="a70b7775e8ec6b930cd1df88c1d691d6a" args="() const " -->
std::string </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#a70b7775e8ec6b930cd1df88c1d691d6a">name</a> () const </td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Returns the name of the db file. <br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">std::string </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#ad108bff8ea5c80026f5ab45d19ec313c">errormsg</a> () const </td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Returns the last error message from sqlite, or an empty string if this object is not opened. <a href="#ad108bff8ea5c80026f5ab45d19ec313c"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#ab7b7609d8dfc4b773c72f80839c38572">open</a> (char const *, long flags=0)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Creates/opens the given db file. <a href="#ab7b7609d8dfc4b773c72f80839c38572"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#a20a1de94fdab6a3e5a604a8776f39e5b">open</a> (std::string const &, long flags=0)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Functionally identical to <a class="el" href="classsq3_1_1database.html#ab7b7609d8dfc4b773c72f80839c38572" title="Creates/opens the given db file.">open(char const*,long)</a>. <a href="#a20a1de94fdab6a3e5a604a8776f39e5b"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#afae8e3a403d29e3ffeec86ccc0570743">close</a> (bool force=false)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">"Closes" this db. <a href="#afae8e3a403d29e3ffeec86ccc0570743"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="aefe363278ea935699a1c9f3d0b0c6e90"></a><!-- doxytag: member="sq3::database::insertid" ref="aefe363278ea935699a1c9f3d0b0c6e90" args="()" -->
<a class="el" href="namespacesq3.html#a9183a4a7baecd3726182653fc57a47ba">int64_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#aefe363278ea935699a1c9f3d0b0c6e90">insertid</a> ()</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Returns the rowid of the most recently inserted row on this db. <br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#a722715171d91b3713e07485fc89f5fda">changes</a> ()</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Returns the number of database rows that were changed (or inserted or deleted) by the most recently completed INSERT, UPDATE, or DELETE statement. <a href="#a722715171d91b3713e07485fc89f5fda"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="a0baa615d200aad7e121f8e11aad12d33"></a><!-- doxytag: member="sq3::database::setbusytimeout" ref="a0baa615d200aad7e121f8e11aad12d33" args="(int ms)" -->
int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#a0baa615d200aad7e121f8e11aad12d33">setbusytimeout</a> (int ms)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">See sqlite3_busy_timeout(). <br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="a65d5e801060b1dad34d539b191305130"></a><!-- doxytag: member="sq3::database::execute" ref="a65d5e801060b1dad34d539b191305130" args="(const std::string &sql)" -->
int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#a65d5e801060b1dad34d539b191305130">execute</a> (const std::string &sql)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Functionally identical to <a class="el" href="classsq3_1_1database.html#a8ff3ede6345e3e242eec5a3225dc5121" title="Executes a statement which is assumed to have a single step and a void result.">execute(char const *)</a>. <br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#a8ff3ede6345e3e242eec5a3225dc5121">execute</a> (char const *sql)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Executes a statement which is assumed to have a single step and a void result. <a href="#a8ff3ede6345e3e242eec5a3225dc5121"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#a702ae3d77fc416e3a99cce89db2725d5">execute</a> (std::string const &sql, int &tgt)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Executes a statement which is assumed to have a single result step and an integer result. <a href="#a702ae3d77fc416e3a99cce89db2725d5"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="acdced556dd72d05d866977de348a7bf7"></a><!-- doxytag: member="sq3::database::execute" ref="acdced556dd72d05d866977de348a7bf7" args="(char const *sql, int &tgt)" -->
int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#acdced556dd72d05d866977de348a7bf7">execute</a> (char const *sql, int &tgt)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">See execute( std::string, int & );. <br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="ac8e93cadab160c9e8a6cb08237245633"></a><!-- doxytag: member="sq3::database::execute" ref="ac8e93cadab160c9e8a6cb08237245633" args="(char const *sql, int64_t &tgt)" -->
int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#ac8e93cadab160c9e8a6cb08237245633">execute</a> (char const *sql, <a class="el" href="namespacesq3.html#a9183a4a7baecd3726182653fc57a47ba">int64_t</a> &tgt)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">See execute( std::string, int & );. <br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="a5369be6be1be26df849152fcf8130ad6"></a><!-- doxytag: member="sq3::database::execute" ref="a5369be6be1be26df849152fcf8130ad6" args="(std::string const &sql, int64_t &tgt)" -->
int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#a5369be6be1be26df849152fcf8130ad6">execute</a> (std::string const &sql, <a class="el" href="namespacesq3.html#a9183a4a7baecd3726182653fc57a47ba">int64_t</a> &tgt)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">See execute( std::string, int & );. <br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="aaf56e701d812206e50321c10d5be9ef0"></a><!-- doxytag: member="sq3::database::execute" ref="aaf56e701d812206e50321c10d5be9ef0" args="(char const *sql, double &tgt)" -->
int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#aaf56e701d812206e50321c10d5be9ef0">execute</a> (char const *sql, double &tgt)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">See execute( std::string, int & );. <br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="a3d01669b93c2189536b3dc00f1b1d95d"></a><!-- doxytag: member="sq3::database::execute" ref="a3d01669b93c2189536b3dc00f1b1d95d" args="(std::string const &sql, double &tgt)" -->
int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#a3d01669b93c2189536b3dc00f1b1d95d">execute</a> (std::string const &sql, double &tgt)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">See execute( std::string, int & );. <br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="a9ca1419e1bddff40a34bf28695cdc240"></a><!-- doxytag: member="sq3::database::execute" ref="a9ca1419e1bddff40a34bf28695cdc240" args="(char const *sql, std::string &tgt)" -->
int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#a9ca1419e1bddff40a34bf28695cdc240">execute</a> (char const *sql, std::string &tgt)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">See execute( std::string, int & );. <br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="aab4aac54b8c566ab303114c7275794cb"></a><!-- doxytag: member="sq3::database::execute" ref="aab4aac54b8c566ab303114c7275794cb" args="(std::string const &sql, std::string &tgt)" -->
int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#aab4aac54b8c566ab303114c7275794cb">execute</a> (std::string const &sql, std::string &tgt)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">See execute( std::string, int & );. <br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#a72a0b07aaf834385214287ea9fd8c2e0">execute</a> (char const *sql, <a class="el" href="namespacesq3.html#a033f4f2b2688f80675078447b55f831f">sqlite3_text_char_t</a> const **tgt, int &len)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">See execute( std::string, int & );. <a href="#a72a0b07aaf834385214287ea9fd8c2e0"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#ab9c770b9d4bd6122ed4fa7e235469e58">execute</a> (std::string const &sql, <a class="el" href="namespacesq3.html#a033f4f2b2688f80675078447b55f831f">sqlite3_text_char_t</a> const **tgt, int &len)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">See <a class="el" href="classsq3_1_1database.html#a72a0b07aaf834385214287ea9fd8c2e0" title="See execute( std::string, int & );.">execute( char const *, sqlite3_text_char_t const **, int & )</a>. <a href="#ab9c770b9d4bd6122ed4fa7e235469e58"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#a2e569222ff4b565f14f94ae228731d06">execute</a> (std::string const &sql, void const **tgt, int &sz)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">See execute( char const *, sqlite3_text_char_t **, int & ). <a href="#a2e569222ff4b565f14f94ae228731d06"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#aea24bc15b9a2357746d2c170108e8bf6">execute</a> (char const *sql, void const **tgt, int &sz)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">See execute( char const *, sqlite3_text_char_t **, int & ). <a href="#aea24bc15b9a2357746d2c170108e8bf6"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#a8f35d75e829113926eb015e011b51ad0">execute</a> (std::string const &sql, sqlite3_callback callback, void *data, std::string &errmsg)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Executes the given query, calling the given callback function for each row of the result set. <a href="#a8f35d75e829113926eb015e011b51ad0"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="a64d2c72d998ccdf01fc90a97001ba078"></a><!-- doxytag: member="sq3::database::execute" ref="a64d2c72d998ccdf01fc90a97001ba078" args="(char const *sql, sqlite3_callback callback, void *data, std::string &errmsg)" -->
int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#a64d2c72d998ccdf01fc90a97001ba078">execute</a> (char const *sql, sqlite3_callback callback, void *data, std::string &errmsg)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Identical to the execute(std::string,sqlite3_callback,void*,std::string&). <br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="a615e275daeda196a48f3f21cef19b6ff"></a><!-- doxytag: member="sq3::database::execute" ref="a615e275daeda196a48f3f21cef19b6ff" args="(std::string const &sql, sqlite3_callback callback, void *data=0)" -->
int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#a615e275daeda196a48f3f21cef19b6ff">execute</a> (std::string const &sql, sqlite3_callback callback, void *data=0)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Convenience overload which has a default data value of 0 and ignores any error string passed back by sqlite3_exec(). <br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="a6a323641fd3d95787dddb1933c15be5a"></a><!-- doxytag: member="sq3::database::execute" ref="a6a323641fd3d95787dddb1933c15be5a" args="(char const *sql, sqlite3_callback callback, void *data=0)" -->
int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#a6a323641fd3d95787dddb1933c15be5a">execute</a> (char const *sql, sqlite3_callback callback, void *data=0)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Convenience overload which has a default data value of 0 and ignores any error string passed back by sqlite3_exec(). <br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#ac9fda7f2a5e13df8a1e7cce2ecb13279">pragma</a> (char const *code)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">This is a convenience wrapper for execute( "pragma ..." ). <a href="#ac9fda7f2a5e13df8a1e7cce2ecb13279"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#a1cd1358658597f872f849691dafc12ed">vacuum</a> ()</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Convenience wrapper around execute("vacuum"). <a href="#a1cd1358658597f872f849691dafc12ed"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#abd2da1a48439fe0bcb4d2f1f1985c9c6">clear</a> ()</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Looks through sqlite_master for a list of views, triggers, and tables, and drops them all (in that order). <a href="#abd2da1a48439fe0bcb4d2f1f1985c9c6"></a><br/></td></tr>
<tr><td colspan="2"><h2>Protected Member Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual int </td><td class="memItemRight" valign="bottom"><a class="el" href="classsq3_1_1database.html#af18c9185b4c73af3c453f54cba13015f">on_open</a> ()</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">This function is called when <a class="el" href="classsq3_1_1database.html#ab7b7609d8dfc4b773c72f80839c38572" title="Creates/opens the given db file.">open()</a> succeeds. <a href="#af18c9185b4c73af3c453f54cba13015f"></a><br/></td></tr>
<tr><td colspan="2"><h2>Friends</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="a4682195a7dfc5da7346d8cfadcf0eb20"></a><!-- doxytag: member="sq3::database::statement" ref="a4682195a7dfc5da7346d8cfadcf0eb20" args="" -->
class </td><td class="memItemRight" valign="bottom"><b>statement</b></td></tr>
</table>
<hr/><a name="_details"></a><h2>Detailed Description</h2>
<p>Encapsulates a connection to an sqlite database. </p>
<p>This type is virtual/subclassable so that clients can add initialization routines to all of their databases, such as adding sqlite-builtin functions and collating sequences. Simply do such initializations in your subclass ctors.</p>
<p>A note on the lack of proper constness for much of this API... Potentially, in the face of triggers, multiple threads, and whatnot, it is not generically possible to 100% ensure that any given SQL statement does *not* modify the database in at least *some* way. To reflect this underlying state of flux, "it was decided" (it really was) that very little, if any, of the members of this class would be const. Only those which could 100% guaranty proper constness.</p>
<p>Notes about copying:</p>
<p>Copying a db object is actually shallow copying. All copies of this type will refer to the same underlying (sqlite3*) db handle until/unless:</p>
<ul>
<li>When <a class="el" href="classsq3_1_1database.html#ab7b7609d8dfc4b773c72f80839c38572" title="Creates/opens the given db file.">open()</a> is called, the object on which it was called may separate itself from the rcptr relationship with the older db handle and start a new one.</li>
</ul>
<ul>
<li>close(false) affects only the calling db. When the reference count for the (sqlite3*) handle drops to zero, then sqlite3_close() will be called. close(true) closes the db handle immediately, affecting all copies of this object.</li>
</ul>
<ul>
<li>When <a class="el" href="classsq3_1_1database.html#a96e7f35f86397c1f82325ec902d66600" title="Transfers ownership of this->handle() to the caller.">take_handle()</a> is called then ownership of the underlying db handle is removed from ALL copies of this object. They will still refer to the handle, but using it is not legal. </li>
</ul>
<p>Definition at line <a class="el" href="sq3_8hpp_source.html#l00191">191</a> of file <a class="el" href="sq3_8hpp_source.html">sq3.hpp</a>.</p>
<hr/><h2>Constructor & Destructor Documentation</h2>
<a class="anchor" id="a031f52c894718d806d3d09696901dcca"></a><!-- doxytag: member="sq3::database::database" ref="a031f52c894718d806d3d09696901dcca" args="()" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">sq3::database::database </td>
<td>(</td>
<td class="paramname"></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Creates an unopened database. </p>
<p>Use <a class="el" href="classsq3_1_1database.html#ab7b7609d8dfc4b773c72f80839c38572" title="Creates/opens the given db file.">open()</a> to open a file or <a class="el" href="classsq3_1_1database.html#a96e7f35f86397c1f82325ec902d66600" title="Transfers ownership of this->handle() to the caller.">take_handle()</a> to transfer an existing db handle to this object. </p>
<p>Definition at line <a class="el" href="sq3_8cpp_source.html#l00544">544</a> of file <a class="el" href="sq3_8cpp_source.html">sq3.cpp</a>.</p>
</div>
</div>
<a class="anchor" id="a5dca436b8be0c07023e8347bb5137a80"></a><!-- doxytag: member="sq3::database::database" ref="a5dca436b8be0c07023e8347bb5137a80" args="(std::string const &filename)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">sq3::database::database </td>
<td>(</td>
<td class="paramtype">std::string const & </td>
<td class="paramname"> <em>filename</em></td>
<td> ) </td>
<td><code> [explicit]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Opens/creates the given db file. </p>
<p>Use <a class="el" href="classsq3_1_1database.html#af3b6b07c453a2ce5eaf9072e9cbe1f84" title="Returns true if this db is opened.">is_open()</a> to see if the opening worked.</p>
<p>Subclasses should not call this from a ctor initialization list because this function may eventually call <a class="el" href="classsq3_1_1database.html#af18c9185b4c73af3c453f54cba13015f" title="This function is called when open() succeeds.">on_open()</a>, which is virtual, but the subclass part of the class may not be in place to catch that virtual call. So subclasses should initialize with the no-arg parent class ctor and should then call open(filename) themselves. </p>
<p>Definition at line <a class="el" href="sq3_8cpp_source.html#l00549">549</a> of file <a class="el" href="sq3_8cpp_source.html">sq3.cpp</a>.</p>
<p>References <a class="el" href="sq3_8cpp_source.html#l00591">open()</a>.</p>
</div>
</div>
<hr/><h2>Member Function Documentation</h2>
<a class="anchor" id="a722715171d91b3713e07485fc89f5fda"></a><!-- doxytag: member="sq3::database::changes" ref="a722715171d91b3713e07485fc89f5fda" args="()" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int sq3::database::changes </td>
<td>(</td>
<td class="paramname"></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Returns the number of database rows that were changed (or inserted or deleted) by the most recently completed INSERT, UPDATE, or DELETE statement. </p>
<p>SQLite implements the command "DELETE FROM table" without a WHERE clause by dropping and recreating the table. To get an accurate count of the number of rows deleted, use "DELETE FROM table WHERE 1" instead. </p>
<p>Definition at line <a class="el" href="sq3_8cpp_source.html#l00684">684</a> of file <a class="el" href="sq3_8cpp_source.html">sq3.cpp</a>.</p>
<p>References <a class="el" href="refcount_8hpp_source.html#l00385">refcount::rcptr< HandleT, FinalizerT >::get()</a>.</p>
</div>
</div>
<a class="anchor" id="abd2da1a48439fe0bcb4d2f1f1985c9c6"></a><!-- doxytag: member="sq3::database::clear" ref="abd2da1a48439fe0bcb4d2f1f1985c9c6" args="()" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int sq3::database::clear </td>
<td>(</td>
<td class="paramname"></td>
<td> ) </td>
<td><code> [virtual]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Looks through sqlite_master for a list of views, triggers, and tables, and drops them all (in that order). </p>
<p>Subclasses are welcomed to reimplement it to do less destructive cleansing, such as just dropping data from a certain table.</p>
<p>Returns SQLITE_OK on success.</p>
<p>If you need to free up the newly-freed space, be sure to call <a class="el" href="classsq3_1_1database.html#a1cd1358658597f872f849691dafc12ed" title="Convenience wrapper around execute("vacuum").">vacuum()</a>, or else the file size may not actually shrink.</p>
<p>Also remember that any code which is expecting data to be in this database will not work after this function is done! </p>
<p>Reimplemented in <a class="el" href="classsq3_1_1log__db.html#af2c6103c4980d3ae24270c6ed618839d">sq3::log_db</a>, and <a class="el" href="classsq3_1_1settings__db.html#af60e1866d8726c56d54f499b4d354e9b">sq3::settings_db</a>.</p>
<p>Definition at line <a class="el" href="sq3_8cpp_source.html#l00827">827</a> of file <a class="el" href="sq3_8cpp_source.html">sq3.cpp</a>.</p>
<p>References <a class="el" href="sq3_8cpp_source.html#l00173">sq3::statement::bind()</a>, <a class="el" href="sq3_8cpp_source.html#l00698">execute()</a>, <a class="el" href="sq3_8cpp_source.html#l00246">sq3::statement::get_cursor()</a>, <a class="el" href="sq3_8cpp_source.html#l00563">is_open()</a>, <a class="el" href="sq3_8cpp_source.html#l00567">name()</a>, and <a class="el" href="sq3_8cpp_source.html#l00056">sq3::rc_is_okay()</a>.</p>
</div>
</div>
<a class="anchor" id="afae8e3a403d29e3ffeec86ccc0570743"></a><!-- doxytag: member="sq3::database::close" ref="afae8e3a403d29e3ffeec86ccc0570743" args="(bool force=false)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int sq3::database::close </td>
<td>(</td>
<td class="paramtype">bool </td>
<td class="paramname"> <em>force</em> = <code>false</code></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>"Closes" this db. </p>
<p>That actually means that it queues it to be closed when the last database object which is using that db handle closes or goes out of scope.</p>
<p>The force parameter changes the handling of those sqlite3_close():</p>
<p>If force is false, this function always returns SQLITE_OK unless this object is already closed, in which case SQLITE_ERROR is returned but can almost certainly be safely ignored. Unfortunately, due to the asynchronous nature of this operation, we can't return the value from the actual sqlite3_close() call (if any) when force is set to false.</p>
<p>If force is true then the internal reference counting is anulled and the db handle is closed immediately. This affects all copies of this object, so use with care (but use if you must). In this case, the value of sqlite3_close() is returned, but the the exact state of the underlying database handle is ambiguously defined in the sqlite3 docs. So... if that happens then the underlying db handle is assumed to be invalid, since the "test*.c" files which come with sqlite3 seem to treat it as such. </p>
<p>Definition at line <a class="el" href="sq3_8cpp_source.html#l00663">663</a> of file <a class="el" href="sq3_8cpp_source.html">sq3.cpp</a>.</p>
<p>References <a class="el" href="refcount_8hpp_source.html#l00385">refcount::rcptr< HandleT, FinalizerT >::get()</a>, and <a class="el" href="refcount_8hpp_source.html#l00394">refcount::rcptr< HandleT, FinalizerT >::take()</a>.</p>
<p>Referenced by <a class="el" href="sq3_8cpp_source.html#l00591">open()</a>, <a class="el" href="sq3_8cpp_source.html#l00577">take_handle()</a>, and <a class="el" href="sq3_8cpp_source.html#l00555">~database()</a>.</p>
</div>
</div>
<a class="anchor" id="ad108bff8ea5c80026f5ab45d19ec313c"></a><!-- doxytag: member="sq3::database::errormsg" ref="ad108bff8ea5c80026f5ab45d19ec313c" args="() const " -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">std::string sq3::database::errormsg </td>
<td>(</td>
<td class="paramname"></td>
<td> ) </td>
<td> const</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Returns the last error message from sqlite, or an empty string if this object is not opened. </p>
<p>Unfortunately, sqlite3 returns the literal string "not an error" on non-errors, instead of returning an empty string. </p>
<p>Definition at line <a class="el" href="sq3_8cpp_source.html#l00585">585</a> of file <a class="el" href="sq3_8cpp_source.html">sq3.cpp</a>.</p>
<p>References <a class="el" href="refcount_8hpp_source.html#l00385">refcount::rcptr< HandleT, FinalizerT >::get()</a>.</p>
</div>
</div>
<a class="anchor" id="a8f35d75e829113926eb015e011b51ad0"></a><!-- doxytag: member="sq3::database::execute" ref="a8f35d75e829113926eb015e011b51ad0" args="(std::string const &sql, sqlite3_callback callback, void *data, std::string &errmsg)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int sq3::database::execute </td>
<td>(</td>
<td class="paramtype">std::string const & </td>
<td class="paramname"> <em>sql</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">sqlite3_callback </td>
<td class="paramname"> <em>callback</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void * </td>
<td class="paramname"> <em>data</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">std::string & </td>
<td class="paramname"> <em>errmsg</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Executes the given query, calling the given callback function for each row of the result set. </p>
<p>The data pointer is passed on as-is to the callback. Any error string is written to errmsg.</p>
<p>Return value is that of an underlying sqlite3_exec() call. </p>
<p>Definition at line <a class="el" href="sq3_8cpp_source.html#l00769">769</a> of file <a class="el" href="sq3_8cpp_source.html">sq3.cpp</a>.</p>
<p>References <a class="el" href="sq3_8cpp_source.html#l00698">execute()</a>.</p>
</div>
</div>
<a class="anchor" id="aea24bc15b9a2357746d2c170108e8bf6"></a><!-- doxytag: member="sq3::database::execute" ref="aea24bc15b9a2357746d2c170108e8bf6" args="(char const *sql, void const **tgt, int &sz)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int sq3::database::execute </td>
<td>(</td>
<td class="paramtype">char const * </td>
<td class="paramname"> <em>sql</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void const ** </td>
<td class="paramname"> <em>tgt</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int & </td>
<td class="paramname"> <em>sz</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>See execute( char const *, sqlite3_text_char_t **, int & ). </p>
<p>This function is identical except that tgt is a void pointer. </p>
<p>Definition at line <a class="el" href="sq3_8cpp_source.html#l00760">760</a> of file <a class="el" href="sq3_8cpp_source.html">sq3.cpp</a>.</p>
</div>
</div>
<a class="anchor" id="a2e569222ff4b565f14f94ae228731d06"></a><!-- doxytag: member="sq3::database::execute" ref="a2e569222ff4b565f14f94ae228731d06" args="(std::string const &sql, void const **tgt, int &sz)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int sq3::database::execute </td>
<td>(</td>
<td class="paramtype">std::string const & </td>
<td class="paramname"> <em>sql</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void const ** </td>
<td class="paramname"> <em>tgt</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int & </td>
<td class="paramname"> <em>sz</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>See execute( char const *, sqlite3_text_char_t **, int & ). </p>
<p>This function is identical except that tgt is a void pointer. </p>
<p>Definition at line <a class="el" href="sq3_8cpp_source.html#l00764">764</a> of file <a class="el" href="sq3_8cpp_source.html">sq3.cpp</a>.</p>
</div>
</div>
<a class="anchor" id="ab9c770b9d4bd6122ed4fa7e235469e58"></a><!-- doxytag: member="sq3::database::execute" ref="ab9c770b9d4bd6122ed4fa7e235469e58" args="(std::string const &sql, sqlite3_text_char_t const **tgt, int &len)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int sq3::database::execute </td>
<td>(</td>
<td class="paramtype">std::string const & </td>
<td class="paramname"> <em>sql</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="namespacesq3.html#a033f4f2b2688f80675078447b55f831f">sqlite3_text_char_t</a> const ** </td>
<td class="paramname"> <em>tgt</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int & </td>
<td class="paramname"> <em>len</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>See <a class="el" href="classsq3_1_1database.html#a72a0b07aaf834385214287ea9fd8c2e0" title="See execute( std::string, int & );.">execute( char const *, sqlite3_text_char_t const **, int & )</a>. </p>
<p>This function is identical. </p>
<p>Definition at line <a class="el" href="sq3_8cpp_source.html#l00753">753</a> of file <a class="el" href="sq3_8cpp_source.html">sq3.cpp</a>.</p>
</div>
</div>
<a class="anchor" id="a72a0b07aaf834385214287ea9fd8c2e0"></a><!-- doxytag: member="sq3::database::execute" ref="a72a0b07aaf834385214287ea9fd8c2e0" args="(char const *sql, sqlite3_text_char_t const **tgt, int &len)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int sq3::database::execute </td>
<td>(</td>
<td class="paramtype">char const * </td>
<td class="paramname"> <em>sql</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="namespacesq3.html#a033f4f2b2688f80675078447b55f831f">sqlite3_text_char_t</a> const ** </td>
<td class="paramname"> <em>tgt</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int & </td>
<td class="paramname"> <em>len</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>See execute( std::string, int & );. </p>
<p>sql is executed and the string result is written to tgt and the length of the result string (in bytes) is written to len. The text bytes are owned by sqlite and will likely become invalid on the next db cursor operation, so copy them if you need them.</p>
<p>Returns the result of stepping through a result set, which is typically one of SQLITE_ROW or SQLITE_DONE. </p>
<p>Definition at line <a class="el" href="sq3_8cpp_source.html#l00748">748</a> of file <a class="el" href="sq3_8cpp_source.html">sq3.cpp</a>.</p>
</div>
</div>
<a class="anchor" id="a702ae3d77fc416e3a99cce89db2725d5"></a><!-- doxytag: member="sq3::database::execute" ref="a702ae3d77fc416e3a99cce89db2725d5" args="(std::string const &sql, int &tgt)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int sq3::database::execute </td>
<td>(</td>
<td class="paramtype">std::string const & </td>
<td class="paramname"> <em>sql</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int & </td>
<td class="paramname"> <em>tgt</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Executes a statement which is assumed to have a single result step and an integer result. </p>
<p>On success, tgt will be set to the query's value. Typically one of SQLITE_ROW or SQLITE_DONE are returned on success. </p>
<p>Definition at line <a class="el" href="sq3_8cpp_source.html#l00713">713</a> of file <a class="el" href="sq3_8cpp_source.html">sq3.cpp</a>.</p>
</div>
</div>
<a class="anchor" id="a8ff3ede6345e3e242eec5a3225dc5121"></a><!-- doxytag: member="sq3::database::execute" ref="a8ff3ede6345e3e242eec5a3225dc5121" args="(char const *sql)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int sq3::database::execute </td>
<td>(</td>
<td class="paramtype">char const * </td>
<td class="paramname"> <em>sql</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Executes a statement which is assumed to have a single step and a void result. </p>
<p>Returned result is that of an underlying call to sqlite3_step(), which means that SQLITE_DONE or SQLITE_ROW evaluate to success. </p>
<p>Definition at line <a class="el" href="sq3_8cpp_source.html#l00703">703</a> of file <a class="el" href="sq3_8cpp_source.html">sq3.cpp</a>.</p>
</div>
</div>
<a class="anchor" id="a674d66007f7cf0fe2f68233593526ecb"></a><!-- doxytag: member="sq3::database::handle" ref="a674d66007f7cf0fe2f68233593526ecb" args="() const " -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">sqlite3 * sq3::database::handle </td>
<td>(</td>
<td class="paramname"></td>
<td> ) </td>
<td> const</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>The low-level handle to the sqlite db. </p>
<p>NEVER close this handle. It is permissible to use it to run queries, add functions to the db, etc.</p>
<p>This object retains ownership of the returned handle. </p>
<p>Definition at line <a class="el" href="sq3_8cpp_source.html#l00540">540</a> of file <a class="el" href="sq3_8cpp_source.html">sq3.cpp</a>.</p>
<p>References <a class="el" href="refcount_8hpp_source.html#l00385">refcount::rcptr< HandleT, FinalizerT >::get()</a>.</p>
<p>Referenced by <a class="el" href="sq3_8cpp_source.html#l00067">sq3::statement::prepare()</a>.</p>
</div>
</div>
<a class="anchor" id="af3b6b07c453a2ce5eaf9072e9cbe1f84"></a><!-- doxytag: member="sq3::database::is_open" ref="af3b6b07c453a2ce5eaf9072e9cbe1f84" args="() const " -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">bool sq3::database::is_open </td>
<td>(</td>
<td class="paramname"></td>
<td> ) </td>
<td> const</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Returns true if this db is opened. </p>
<p>Does not detect errors such as opening a non-db file. </p>
<p>Definition at line <a class="el" href="sq3_8cpp_source.html#l00563">563</a> of file <a class="el" href="sq3_8cpp_source.html">sq3.cpp</a>.</p>
<p>References <a class="el" href="refcount_8hpp_source.html#l00385">refcount::rcptr< HandleT, FinalizerT >::get()</a>.</p>
<p>Referenced by <a class="el" href="sq3_8cpp_source.html#l00827">clear()</a>.</p>
</div>
</div>
<a class="anchor" id="af18c9185b4c73af3c453f54cba13015f"></a><!-- doxytag: member="sq3::database::on_open" ref="af18c9185b4c73af3c453f54cba13015f" args="()" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int sq3::database::on_open </td>
<td>(</td>
<td class="paramname"></td>
<td> ) </td>
<td><code> [protected, virtual]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>This function is called when <a class="el" href="classsq3_1_1database.html#ab7b7609d8dfc4b773c72f80839c38572" title="Creates/opens the given db file.">open()</a> succeeds. </p>
<p>The default implementation does nothing and always returns SQLITE_OK, but subclasses may wish to do something here. If this function returns any value other than SQLITE_OK then this-><a class="el" href="classsq3_1_1database.html#afae8e3a403d29e3ffeec86ccc0570743" title=""Closes" this db.">close()</a> is called before <a class="el" href="classsq3_1_1database.html#ab7b7609d8dfc4b773c72f80839c38572" title="Creates/opens the given db file.">open()</a> returns. </p>
<p>Reimplemented in <a class="el" href="classsq3_1_1log__db.html#a1b654e2c000d3497f723848cd358f24e">sq3::log_db</a>.</p>
<p>Definition at line <a class="el" href="sq3_8cpp_source.html#l00632">632</a> of file <a class="el" href="sq3_8cpp_source.html">sq3.cpp</a>.</p>
<p>Referenced by <a class="el" href="sq3_8cpp_source.html#l00591">open()</a>.</p>
</div>
</div>
<a class="anchor" id="a20a1de94fdab6a3e5a604a8776f39e5b"></a><!-- doxytag: member="sq3::database::open" ref="a20a1de94fdab6a3e5a604a8776f39e5b" args="(std::string const &, long flags=0)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int sq3::database::open </td>
<td>(</td>
<td class="paramtype">std::string const & </td>
<td class="paramname"> <em>dbn</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">long </td>
<td class="paramname"> <em>flags</em> = <code>0</code></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Functionally identical to <a class="el" href="classsq3_1_1database.html#ab7b7609d8dfc4b773c72f80839c38572" title="Creates/opens the given db file.">open(char const*,long)</a>. </p>
<p>This function calls that one, so subclasses wishing to change <a class="el" href="classsq3_1_1database.html#ab7b7609d8dfc4b773c72f80839c38572" title="Creates/opens the given db file.">open()</a>'s behaviour need only reimplement that one. </p>
<p>Definition at line <a class="el" href="sq3_8cpp_source.html#l00627">627</a> of file <a class="el" href="sq3_8cpp_source.html">sq3.cpp</a>.</p>
<p>References <a class="el" href="sq3_8cpp_source.html#l00591">open()</a>.</p>
</div>
</div>
<a class="anchor" id="ab7b7609d8dfc4b773c72f80839c38572"></a><!-- doxytag: member="sq3::database::open" ref="ab7b7609d8dfc4b773c72f80839c38572" args="(char const *, long flags=0)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int sq3::database::open </td>
<td>(</td>
<td class="paramtype">char const * </td>
<td class="paramname"> <em>dbn</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">long </td>
<td class="paramname"> <em>flags</em> = <code>0</code></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td><code> [virtual]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Creates/opens the given db file. </p>
<p>The flags parameter is only used if this code is compiled against sqlite3 >= 3.5.1, and can theoretically take any values defined in the SQLITE_OPEN_xxx family of macros. The sqlite3 documentation only describes the use of SQLITE_OPEN_READONLY, SQLITE_OPEN_READWRITE, and SQLITE_OPEN_CREATE, thus other values may nor may not work. If (0==flags) then (SQLITE_OPEN_READWRITE|SQLITE_OPEN_CREATE) is assumed. See sqlite3_open_v2() for the exact semantics.</p>
<p>On success it returns SQLITE_OK, or some other value on error.</p>
<p>Calling <a class="el" href="classsq3_1_1database.html#ab7b7609d8dfc4b773c72f80839c38572" title="Creates/opens the given db file.">open()</a> will implicitly call <a class="el" href="classsq3_1_1database.html#afae8e3a403d29e3ffeec86ccc0570743" title=""Closes" this db.">close()</a> on any existing connection. If that <a class="el" href="classsq3_1_1database.html#afae8e3a403d29e3ffeec86ccc0570743" title=""Closes" this db.">close()</a> fails then this <a class="el" href="classsq3_1_1database.html#ab7b7609d8dfc4b773c72f80839c38572" title="Creates/opens the given db file.">open()</a> will also fail. If the <a class="el" href="classsq3_1_1database.html#ab7b7609d8dfc4b773c72f80839c38572" title="Creates/opens the given db file.">open()</a> succeeds, it does NOT affect other (shallow) copies of this object: they will still refer to the older db handle.</p>
<p>Note that sqlite3 supports the special db name ":memory:" to represent an in-memory database. Such databases cannot be saved directly to disk and are lost when this object closes the db.</p>
<p>Windows users beware: according to the sqlite3 documentation, the db name MUST be in UTF8 format, regardless of the current codepage used by Windows, and it is the caller's responsibility to perform any conversion, if needed.</p>
<p>Internal notes:</p>
<p>If the underlying sqlite3_open() succeeds, the protected member <a class="el" href="classsq3_1_1database.html#af18c9185b4c73af3c453f54cba13015f" title="This function is called when open() succeeds.">on_open()</a> in called. If it returns a value other than SQLITE_OK then this-><a class="el" href="classsq3_1_1database.html#afae8e3a403d29e3ffeec86ccc0570743" title=""Closes" this db.">close()</a> is called and the value returned from <a class="el" href="classsq3_1_1database.html#af18c9185b4c73af3c453f54cba13015f" title="This function is called when open() succeeds.">on_open()</a> is returned from this function.</p>
<p>Subclasses which override this function and do not want to call the base implementation should call <a class="el" href="classsq3_1_1database.html#af18c9185b4c73af3c453f54cba13015f" title="This function is called when open() succeeds.">on_open()</a> when done to allow subclasses to initialize the database if they like. If <a class="el" href="classsq3_1_1database.html#af18c9185b4c73af3c453f54cba13015f" title="This function is called when open() succeeds.">on_open()</a> fails then this-><a class="el" href="classsq3_1_1database.html#afae8e3a403d29e3ffeec86ccc0570743" title=""Closes" this db.">close()</a> should be called to free up the resources and mark this object as unopened.</p>
<p>The flags argument was added 20071018, suggested by Joaquim Campos Salles (Joaquim.Salles at br.unisys.com). </p>
<p>Definition at line <a class="el" href="sq3_8cpp_source.html#l00591">591</a> of file <a class="el" href="sq3_8cpp_source.html">sq3.cpp</a>.</p>
<p>References <a class="el" href="sq3_8cpp_source.html#l00663">close()</a>, <a class="el" href="refcount_8hpp_source.html#l00385">refcount::rcptr< HandleT, FinalizerT >::get()</a>, <a class="el" href="sq3_8cpp_source.html#l00632">on_open()</a>, and <a class="el" href="refcount_8hpp_source.html#l00394">refcount::rcptr< HandleT, FinalizerT >::take()</a>.</p>
<p>Referenced by <a class="el" href="sq3_8cpp_source.html#l00549">database()</a>, <a class="el" href="sq3_8cpp_source.html#l00627">open()</a>, and <a class="el" href="sq3__log__db_8cpp_source.html#l00011">sq3::log_db::~log_db()</a>.</p>
</div>
</div>
<a class="anchor" id="ac9fda7f2a5e13df8a1e7cce2ecb13279"></a><!-- doxytag: member="sq3::database::pragma" ref="ac9fda7f2a5e13df8a1e7cce2ecb13279" args="(char const *code)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int sq3::database::pragma </td>
<td>(</td>
<td class="paramtype">char const * </td>
<td class="paramname"> <em>code</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>This is a convenience wrapper for execute( "pragma ..." ). </p>
<p>Return value is that of the underlying <a class="el" href="classsq3_1_1database.html#a65d5e801060b1dad34d539b191305130" title="Functionally identical to execute(char const *).">execute()</a> call.</p>
<p>code should be a pragma key or key/value string, such as "temp_store=MEMORY" or "synchronous=OFF" </p>
<p>Definition at line <a class="el" href="sq3_8cpp_source.html#l00814">814</a> of file <a class="el" href="sq3_8cpp_source.html">sq3.cpp</a>.</p>
<p>References <a class="el" href="sq3_8cpp_source.html#l00698">execute()</a>.</p>
</div>
</div>
<a class="anchor" id="a96e7f35f86397c1f82325ec902d66600"></a><!-- doxytag: member="sq3::database::take_handle" ref="a96e7f35f86397c1f82325ec902d66600" args="()" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">sqlite3 * sq3::database::take_handle </td>
<td>(</td>
<td class="paramname"></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Transfers ownership of this-><a class="el" href="classsq3_1_1database.html#a674d66007f7cf0fe2f68233593526ecb" title="The low-level handle to the sqlite db.">handle()</a> to the caller. </p>
<p>ALL copies of this object which point to the handle, except for this copy, still have a pointer to that handle but will not call the handle dtor when they go out of scope or are closed. </p>
<p>Definition at line <a class="el" href="sq3_8cpp_source.html#l00572">572</a> of file <a class="el" href="sq3_8cpp_source.html">sq3.cpp</a>.</p>
<p>References <a class="el" href="refcount_8hpp_source.html#l00394">refcount::rcptr< HandleT, FinalizerT >::take()</a>.</p>
</div>
</div>
<a class="anchor" id="acf216ebb32313e51215468aec2ef0952"></a><!-- doxytag: member="sq3::database::take_handle" ref="acf216ebb32313e51215468aec2ef0952" args="(sqlite3 *dbh, std::string const &name="")" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void sq3::database::take_handle </td>
<td>(</td>
<td class="paramtype">sqlite3 * </td>
<td class="paramname"> <em>dbh</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">std::string const & </td>
<td class="paramname"> <em>name</em> = <code>""</code></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>dbh is assumed to be an opened, valid db handle. </p>
<p>This function transfers ownership of dbh to this object. Specifically, dbh will be closed when the last database with the same db handle goes out of scope or is closed. The name is simply informative, and may or may not be the same actually used for opening dbh.</p>
<p>Note that this function does not call the protected this-><a class="el" href="classsq3_1_1database.html#af18c9185b4c73af3c453f54cba13015f" title="This function is called when open() succeeds.">on_open()</a> because, quite frankly, i'm not yet sure if it really makes sense to do so. </p>
<p>Definition at line <a class="el" href="sq3_8cpp_source.html#l00577">577</a> of file <a class="el" href="sq3_8cpp_source.html">sq3.cpp</a>.</p>
<p>References <a class="el" href="sq3_8cpp_source.html#l00663">close()</a>, <a class="el" href="refcount_8hpp_source.html#l00385">refcount::rcptr< HandleT, FinalizerT >::get()</a>, and <a class="el" href="refcount_8hpp_source.html#l00394">refcount::rcptr< HandleT, FinalizerT >::take()</a>.</p>
</div>
</div>
<a class="anchor" id="a1cd1358658597f872f849691dafc12ed"></a><!-- doxytag: member="sq3::database::vacuum" ref="a1cd1358658597f872f849691dafc12ed" args="()" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int sq3::database::vacuum </td>
<td>(</td>
<td class="paramname"></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Convenience wrapper around execute("vacuum"). </p>
<p>The vacuum operation attempts to free up any unused disk space in the database. </p>
<p>Definition at line <a class="el" href="sq3_8cpp_source.html#l00822">822</a> of file <a class="el" href="sq3_8cpp_source.html">sq3.cpp</a>.</p>
<p>References <a class="el" href="sq3_8cpp_source.html#l00698">execute()</a>.</p>
</div>
</div>
<hr/>The documentation for this class was generated from the following files:<ul>
<li><a class="el" href="sq3_8hpp_source.html">sq3.hpp</a></li>
<li><a class="el" href="sq3_8cpp_source.html">sq3.cpp</a></li>
</ul>
</div>
<hr class="footer"/><address style="text-align: right;"><small>Generated by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.2-20100208 </small></address>
</body>
</html>
