<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.10 $ -->
<refentry id="function.sqlite-popen">
 <refnamediv>
  <refname>sqlite_popen</refname>
  <refpurpose>
   Opens a persistent handle to an SQLite database and create the database if it does not exist
  </refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>resource</type><methodname>sqlite_popen</methodname>
   <methodparam><type>string</type><parameter>filename</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>mode</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter role="reference">error_message</parameter></methodparam>
  </methodsynopsis>
  <simpara>
   This function behaves identically to <function>sqlite_open</function>
   except that is uses the persistent resource mechanism of PHP.
   For information about the meaning of the parameters, read the
   <function>sqlite_open</function> manual page.
  </simpara>
  <para>
   <function>sqlite_popen</function> will first check to see if a persistent
   handle has already been opened for the given
   <parameter>filename</parameter>.  If it finds one, it returns that handle
   to your script, otherwise it opens a fresh handle to the database.
  </para>
  <para>
   The benefit of this approach is that you don't incur the performance
   cost of re-reading the database and index schema on each page hit served
   by persistent web server SAPI's (any SAPI except for regular CGI or CLI).
  </para>
  <note>
   <simpara>
    If you use persistent handles and have the database updated by a
    background process (perhaps via a crontab), and that process re-creates
    the database by overwriting it (either by unlinking and rebuilding, or
    moving the updated version to replace the current version),
    you may experience undefined behaviour when a persistent handle on the
    old version of the database is recycled.
   </simpara>
   <simpara>
    To avoid this situation, have your background processes open the same
    database file and perform their updates in a transaction.
   </simpara>
  </note>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>filename</parameter></term>
     <listitem>
      <para>
       The filename of the SQLite database.  If the file does not exist, SQLite
       will attempt to create it.  PHP must have write permissions to the file
       if data is inserted, the database schema is modified or to create the
       database if it does not exist.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>mode</parameter></term>
     <listitem>
      <para>
       The mode of the file. Intended to be used to open the database in
       read-only mode.  Presently, this parameter is ignored by the sqlite
       library.  The default value for mode is the octal value
       <literal>0666</literal> and this is the recommended value.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>error_message</parameter></term>
     <listitem>
      <para>
       Passed by reference and is set to hold a descriptive error message
       explaining why the database could not be opened if there was an error.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns a resource (database handle) on success, &false; on error.
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>sqlite_open</function></member>
    <member><function>sqlite_close</function></member>
    <member><function>sqlite_factory</function></member>
   </simplelist>
  </para>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
 sgml-omittag:t
 sgml-shorttag:t
 sgml-minimize-attributes:nil
 sgml-always-quote-attributes:t
 sgml-indent-step:1
 sgml-indent-data:t
 sgml-parent-document:nil
 sgml-default-dtd-file:"../../manual.ced"
 sgml-exposed-tags:nil
 sgml-local-catalogs:nil
 sgml-local-ecat-files:nil
 End:
 vim600: syn=xml fen fdm=syntax fdl=2 si
 vim: et tw=78 syn=sgml
 vi: ts=1 sw=1
 -->