<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.8 $ -->
<!-- splitted from ./en/functions/dba.xml, last change in rev 1.2 -->
  <refentry id="function.dba-open">
   <refnamediv>
    <refname>dba_open</refname>
    <refpurpose>Open database</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>resource</type><methodname>dba_open</methodname>
      <methodparam><type>string</type><parameter>path</parameter></methodparam>
      <methodparam><type>string</type><parameter>mode</parameter></methodparam>
      <methodparam><type>string</type><parameter>handler</parameter></methodparam>
      <methodparam choice="opt"><parameter>...</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>dba_open</function> establishes a database instance for
     <parameter>path</parameter> with <parameter>mode</parameter> using
     <parameter>handler</parameter>.
    </para>
    <para>
     <parameter>path</parameter> is commonly a regular path in your filesystem.
    </para>
    <para>
     <parameter>mode</parameter> is "r" for read access, "w" for read/write
     access to an already existing database, "c" for read/write access
     and database creation if it doesn't currently exist, and "n" for
     create, truncate and read/write access. Additional you can set the databse
     lock method with the next char. Use "l" to lock the database with an .lck 
     file or "d" to lock the databasefile itself. It is important that all of 
     your applications do this consistently. If you want to test the access and 
     do not want to wait for the lock you can add "t" as third character. When 
     you are absolutly sure that you do not require database locking you can do 
     so by using "-" instead of "l" or "d". When none of "d", "l" or "-" is used
     dba will lock on the database file as it would with "d".
    </para>
    <para>
     <parameter>handler</parameter> is the <link linkend="dba.requirements">name
     of the handler</link> which shall be
     used for accessing <parameter>path</parameter>. It is passed all optional
     parameters given to <function>dba_open</function> and can act on behalf of
     them.
    </para>
    <para>
     <function>dba_open</function> returns a positive handle or &false;, in
     the case the database was opened successfull or fails, respectively.
    </para>
    <note>
     <para>
      There can only be one writer for one database file. When you use dba on 
      a webserver and more than one request requires write operations they can
      only be done one after another. Also read during write is not allowed.
      The dba extension uses locks to prevent this. See the follwoing table:
      <table>
       <title>DBA locking</title>
       <tgroup cols="9">
        <thead>
         <row>
          <entry>already open</entry>
          <entry><parameter>mode</parameter> = "rl"</entry>
          <entry><parameter>mode</parameter> = "rlt"</entry>
          <entry><parameter>mode</parameter> = "wl"</entry>
          <entry><parameter>mode</parameter> = "wlt"</entry>
          <entry><parameter>mode</parameter> = "rd"</entry>
          <entry><parameter>mode</parameter> = "rdt"</entry>
          <entry><parameter>mode</parameter> = "wd"</entry>
          <entry><parameter>mode</parameter> = "wdt"</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry>not open</entry>
          <entry>ok</entry>
          <entry>ok</entry>
          <entry>ok</entry>
          <entry>ok</entry>
          <entry>ok</entry>
          <entry>ok</entry>
          <entry>ok</entry>
          <entry>ok</entry>
         </row>
         <row>
          <entry><parameter>mode</parameter> = "rl"</entry>
          <entry>ok</entry>
          <entry>ok</entry>
          <entry>wait</entry>
          <entry>false</entry>
          <entry>illegal</entry>
          <entry>illegal</entry>
          <entry>illegal</entry>
          <entry>illegal</entry>
         </row>
         <row>
          <entry><parameter>mode</parameter> = "wl"</entry>
          <entry>wait</entry>
          <entry>false</entry>
          <entry>wait</entry>
          <entry>false</entry>
          <entry>illegal</entry>
          <entry>illegal</entry>
          <entry>illegal</entry>
          <entry>illegal</entry>
         </row>
         <row>
          <entry><parameter>mode</parameter> = "rd"</entry>
          <entry>illegal</entry>
          <entry>illegal</entry>
          <entry>illegal</entry>
          <entry>illegal</entry>
          <entry>ok</entry>
          <entry>ok</entry>
          <entry>wait</entry>
          <entry>false</entry>
         </row>
         <row>
          <entry><parameter>mode</parameter> = "wd"</entry>
          <entry>illegal</entry>
          <entry>illegal</entry>
          <entry>illegal</entry>
          <entry>illegal</entry>
          <entry>wait</entry>
          <entry>false</entry>
          <entry>wait</entry>
          <entry>false</entry>
         </row>
        </tbody>
       </tgroup>
      </table>
      <simplelist>
       <member>ok: the second call will be successfull.</member>
       <member>wait: the second call waits until <function>dba_close</function> is called for the first.</member>
       <member>false: the second call returns false.</member>
       <member>illegal: you must not mix "l" and "d" modifiers for <parameter>mode</parameter> parameter.</member>
      </simplelist>
     </para>
    </note>
    <note>
     <para>
      Since PHP 4.3.0 it is possible to open database files over network connection.
      However in cases a socket connection will be used (as with http or ftp) the
      connection will be locked instead of the resource itself. This is important to
      know since in such cases locking is simply ignored on the resource and other
      solutions have to be found.
     </para>
    </note>
    <note>
     <para>
      Locking and the <parameter>mode</parameter> modifiers "l", "d", "-" and "t" were
      added in PHP 4.3.0.
      In PHP versions before PHP 4.3.0 you must use semaphores to guard against
      simultanious database access for any database handler with the exception of
      GDBM. See <link linkend="ref.sem">System V semaphore support</link>.
     </para>
    </note>
    <para>
     See also:
     <function>dba_popen</function>
     <function>dba_close</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
indent-tabs-mode:nil
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
-->