cintro.html

嵌入式数据库sqlite 3.5.9的文档

<a href="c3ref/finalize.html">sqlite3_finalize()</a></td>
<td valign="top">
  This routine destroys a 
<a href="c3ref/stmt.html">prepared statement</a> created by a prior call
  to 
<a href="c3ref/prepare.html">sqlite3_prepare()</a>.  Every prepared statement must be destroyed using
  a call to this routine in order to avoid memory leaks.
</td>

<tr><td valign="top" align="right">
<a href="c3ref/close.html">sqlite3_close()</a></td>
<td valign="top">
  This routine closes a 
<a href="c3ref/sqlite3.html">database connection</a> previously opened by a call
  to 
<a href="c3ref/open.html">sqlite3_open()</a>.  All 
<a href="c3ref/stmt.html">prepared statements</a> associated with the
  connection should be 
<a href="c3ref/finalize.html">finalized</a> prior to closing the
  connection.
</td>

</table>


<h3>1.1 Typical Usage Of Core Routines And Objects</h3>


<p>
  An application that wants to use SQLite will typically use
  
<a href="c3ref/open.html">sqlite3_open()</a> to create a single 
<a href="c3ref/sqlite3.html">database connection</a>
  during initialization.
  Note that 
<a href="c3ref/open.html">sqlite3_open()</a> can be used to either open existing database
  files or to create and open new database files.
  While many applications use only a single 
<a href="c3ref/sqlite3.html">database connection</a>, there is
  no reason why an application cannot call 
<a href="c3ref/open.html">sqlite3_open()</a> multiple times
  in order to open multiple 
<a href="c3ref/sqlite3.html">database connections</a> - either to the same
  database or to different databases.  Sometimes a multi-threaded application
  will create separate 
<a href="c3ref/sqlite3.html">database connections</a> for each threads.
  Note too that is not necessary to open separate database connections in
  order to access two or more databases.  A single 
<a href="c3ref/sqlite3.html">database connection</a>
  can be made to access two or more databases at one time using the
  
<a href="lang_attach.html">ATTACH</a> SQL command.
</p>

<p>
  Many applications destroy their 
<a href="c3ref/sqlite3.html">database connections</a> using calls to
  
<a href="c3ref/close.html">sqlite3_close()</a> at shutdown.  Or, for example, an application might
  open 
<a href="c3ref/sqlite3.html">database connections</a> in response to a File->Open menu action
  and then destroy the corresponding 
<a href="c3ref/sqlite3.html">database connection</a> in response
  to the File->Close menu.
</p>

<p>
  To run an SQL statement, the application follows these steps:
</p>

<p><ol>
  <li> Create a 
<a href="c3ref/stmt.html">prepared statement</a> using 
<a href="c3ref/prepare.html">sqlite3_prepare()</a>. </li>
  <li> Evaluate the 
<a href="c3ref/stmt.html">prepared statement</a> by calling 
<a href="c3ref/step.html">sqlite3_step()</a> one
       or more times. </li>
  <li> For queries, extract results by calling 
       
<a href="c3ref/column_blob.html">sqlite3_column()</a> in between
       two calls to 
<a href="c3ref/step.html">sqlite3_step()</a>. </li>
  <li> Destroy the 
<a href="c3ref/stmt.html">prepared statement</a> using 
<a href="c3ref/finalize.html">sqlite3_finalize()</a>. </li>
</ol></p>

<p>
  The foregoing is all one really needs to know in order to use SQLite
  effectively.  All the rest is just ornimentation and detail.
</p>


<h2>2.0 Convenience Wrappers Around Core Routines</h2>


<p>
  The 
<a href="c3ref/exec.html">sqlite3_exec()</a> interface is a convenience wrapper that carries out
  all four of the above steps with a single function call.  A callback
  function passed into 
<a href="c3ref/exec.html">sqlite3_exec()</a> is used to process each row of
  the result set.  The 
<a href="c3ref/free_table.html">sqlite3_get_table()</a> is another convenience wrapper
  that does all four of the above steps.  The 
<a href="c3ref/free_table.html">sqlite3_get_table()</a> interface
  differs from 
<a href="c3ref/free_table.html">sqlite3_get_table()</a> in that it stores the results of queries
  in help memory rather than invoking a callback.
</p>

<p>
  It is important to realize that neither 
<a href="c3ref/exec.html">sqlite3_exec()</a> nor
  
<a href="c3ref/free_table.html">sqlite3_get_table()</a> do anything that cannot be accomplished using
  the core routines.  In fact, these wrappers are implemented purely in
  terms of the core routines.
</p>



<h2>3.0 Binding Parameters and Reusing Prepared Statements</h2>


<p>
  In prior discussion, it was assumed that each SQL statement is prepared
  onces, evaluated, then destroyed.  However, the SQLite allows the same
  
<a href="c3ref/stmt.html">prepared statement</a> to evaluated multiple times.  These is accomplished
  using the following routines:
</p>

<p><ul>
  <li> 
<a href="c3ref/reset.html">sqlite3_reset()</a> </li>
  <li> 
<a href="c3ref/bind_blob.html">sqlite3_bind()</a> </li>
</ul></p>

<p>
  After a 
<a href="c3ref/stmt.html">prepared statement</a> has been evaluated by one or more calls to
  
<a href="c3ref/step.html">sqlite3_step()</a>, it can be reset in order to be evaluted again by a
  single call to 
<a href="c3ref/reset.html">sqlite3_reset()</a>.
  Using 
<a href="c3ref/reset.html">sqlite3_reset()</a> on an existing 
<a href="c3ref/stmt.html">prepared statement</a> rather
  creating a new 
<a href="c3ref/stmt.html">prepared statement</a> avoids unnecessary calls to
  
<a href="c3ref/prepare.html">sqlite3_prepare()</a>.
  In many SQL statements, the time needed
  to run 
<a href="c3ref/prepare.html">sqlite3_prepare()</a> equals or exceeds the time needed by
  
<a href="c3ref/step.html">sqlite3_step()</a>.  So avoiding calls to 
<a href="c3ref/prepare.html">sqlite3_prepare()</a> can result
  in a significant performance improvement.
</p>

<p>
  Usually, though, it is not useful to evaluate exactly the same SQL
  statement more than once.  More often, one wants to evalute similar
  statements.  For example, you might want to evaluate an INSERT statement
  multiple times though with different values to insert.  To accommodate
  this kind of flexibility, SQLite allows SQL statements to contain parameters
  which are "bound" to values prior to being evaluated.  These values can
  later be changed and the same 
<a href="c3ref/stmt.html">prepared statement</a> can be evaluated
  a second time using the new values.
</p>

<p>
  In SQLite, whereever it is valid to include a string literal, one can use
  a parameter in one of the following forms:
</p>

<p><ul>
  <li> <b>?</b> </li>
  <li> <b>?</b><i>NNN</i> </li>
  <li> <b>:</b><i>AAA</i> </li>
  <li> <b>$</b><i>AAA</i> </li>
  <li> <b>@</b><i>AAA</i> </li>
</ul></p>

<p>
  In the examples above, <i>NNN</i> is an integer value and
  <i>AAA</i> is an identifier.
  A parameter initially has a value of NULL.
  Prior to calling 
<a href="c3ref/step.html">sqlite3_step()</a> for the first time or immediately
  after 
<a href="c3ref/reset.html">sqlite3_reset()</a>, the application can invoke one of the
  
<a href="c3ref/bind_blob.html">sqlite3_bind()</a> interfaces to attach values
  to the parameters.  Each call to 
<a href="c3ref/bind_blob.html">sqlite3_bind()</a>
  overrides prior bindings on the same parameter.
</p>

<p>
  An application is allows to prepare multiple SQL statements in advance
  and evaluate them as needed.
  There is no arbitrary limit to the number of outstanding
  
<a href="c3ref/stmt.html">prepared statements</a>.
</p>


<h2>4.0 Extending SQLite</h2>


<p>
  SQLite includes interface that can be used to extend its functionality.
  Such routines include:
</p>

<p><ul>
  <li> 
<a href="c3ref/create_collation.html">sqlite3_create_collation()</a> </li>
  <li> 
<a href="c3ref/create_function.html">sqlite3_create_function()</a> </li>
  <li> 
<a href="c3ref/create_module.html">sqlite3_create_module()</a> </li>
</ul></p>

<p>
  The 
<a href="c3ref/create_collation.html">sqlite3_create_collation()</a> interface is used to create new
  collating sequences for sorting text.
  The 
<a href="c3ref/create_module.html">sqlite3_create_module()</a> interface is used register new
  virtual table implementations.
</p>

<p>
  The 
<a href="c3ref/create_function.html">sqlite3_create_function()</a> interface creates new SQL functions - 
  either scalar or aggregate.  The new function implementation typically
  make use of the following additional interfaces:
</p>

<p><ul>
  <li> 
<a href="c3ref/aggregate_context.html">sqlite3_aggregate_context()</a> </li>
  <li> 
<a href="c3ref/result_blob.html">sqlite3_result()</a> </li>
  <li> 
<a href="c3ref/user_data.html">sqlite3_user_data()</a> </li>
  <li> 
<a href="c3ref/value_blob.html">sqlite3_value()</a> </li>
</ul></p>

<p>
  All of the built-in SQL functions of SQLite are created using exactly
  these same interfaces.  Refer to the SQLite source code, and in particular
  the <b>date.c</b> and <b>func.c</b> source files for examples.
</p>


<h2>5.0 Other Interfaces</h2>


<p>
  This article only mentions the foundational SQLite interfaces.
  The SQLite library includes many other APIs implementing useful
  features that are not described here.  
  A 
<a href="c3ref/funclist.html">complete list of functions</a> that form the SQLite
  application program interface is found at the
  
<a href="c3ref/intro.html">C/C++ Interface Specification</a>.
  Refer to that document for complete and authoritative information about
  all SQLite interfaces.
</p>

<hr><small><i>
This page last modified 2008/05/12 13:08:44 UTC
</i></small></div></body></html>