<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.15 $ -->
<refentry id="function.sqlite-open">
 <refnamediv>
  <refname>sqlite_open</refname>
  <refpurpose>Opens a SQLite database and create the database if it does not exist</refpurpose>
 </refnamediv>
 <refsect1>
  <title>Description</title>
  <methodsynopsis>
   <type>resource</type><methodname>sqlite_open</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>
  <para>Object oriented style (constructor):</para>
  <classsynopsis>
   <ooclass><classname>SQLiteDatabase</classname></ooclass>
   <constructorsynopsis>
    <methodname>__construct</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>
   </constructorsynopsis>
  </classsynopsis>
  <para>
   Returns a resource (database handle) on success, &false; on error.
  </para>
  <para>
   The <parameter>filename</parameter> parameter is the name of the
   database.  It can be a relative or absolute path to the file that sqlite
   will use to store your data.  If the file does not exist, sqlite will
   attempt to create it.  You <emphasis>MUST</emphasis> have write
   permissions to the file if you want to insert data or modify the database
   schema.
  </para>
  <para>
   The <parameter>mode</parameter> parameter specifies the mode of the file and is
   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 to use if you need access to the
   <parameter>errmessage</parameter> parameter.
  </para>
  <para>
   <parameter>errmessage</parameter> is 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>
  <para>
   <example>
    <title><function>sqlite_open</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
if ($db = sqlite_open('mysqlitedb', 0666, $sqliteerror)) { 
    sqlite_query($db, 'CREATE TABLE foo (bar varchar(10))');
    sqlite_query($db, "INSERT INTO foo VALUES ('fnord')");
    $result = sqlite_query($db, 'select bar from foo');
    var_dump(sqlite_fetch_array($result)); 
} else {
    die($sqliteerror);
}
?>]]>
    </programlisting>
   </example>
  </para>
  <tip>
   <simpara>
    On Unix platforms, SQLite is sensitive to scripts that use the fork() system call.  If you
    do have such a script, it is recommended that you close the handle prior
    to forking and then re-open it in the child and/or parent.
    For more information on this issue, see 
    <ulink url="&url.sqlite.interface.c;">The C language interface
    to the SQLite library</ulink> in the section entitled
    <literal>Multi-Threading And SQLite</literal>. 
   </simpara>
  </tip>
  <tip>
   <simpara>
    It is not recommended to work with SQLite databases mounted on NFS
    partitions.  Since NFS is notoriously bad when it comes to locking you
    may find that you cannot even open the database at all, and if it
    succeeds, the locking behaviour may be undefined.
   </simpara>
  </tip>
  <note>
   <simpara>
    Starting with SQLite library version 2.8.2, you can specify
    <literal>:memory:</literal> as the <parameter>filename</parameter> to
    create a database that lives only in the memory of the computer.
    This is useful mostly for temporary processing, as the in-memory
    database will be destroyed when the process ends.  It can also be
    useful when coupled with the <literal>ATTACH DATABASE</literal> SQL
    statement to load other databases and move and query data between them.
   </simpara>
  </note>
  <note>
   <simpara>
    SQLite is &safemode; and open_basedir aware.
   </simpara>
  </note>

  <para>
   See also <function>sqlite_popen</function>,
   <function>sqlite_factory</function>,
   <function>sqlite_close</function> and
   <function>sqlite_query</function>.
  </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
 -->