dba-open.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 44428b04b7b046593e9ab33874eddd1fea7dfab1 Maintainer: yannick Status: ready -->
<!-- Reviewed: no Maintainer: yannick -->

<refentry xml:id="function.dba-open" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>dba_open</refname>
  <refpurpose>Ouvre une base de données DBA</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>Dba\Connection</type><type>false</type></type><methodname>dba_open</methodname>
   <methodparam><type>string</type><parameter>path</parameter></methodparam>
   <methodparam><type>string</type><parameter>mode</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>handler</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>permission</parameter><initializer>0644</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>map_size</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>flags</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>dba_open</function> établit une connexion à
   la base identifiée par <parameter>path</parameter> avec le
   mode <parameter>mode</parameter> et l'identifiant 
   <parameter>handler</parameter>.
  </para>
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>path</parameter></term>
     <listitem>
      <para>
       Chemin sur votre système de fichiers.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>mode</parameter></term>
     <listitem>
      <para>
       Il vaut <literal>r</literal> pour lecture seule, <literal>w</literal> pour
       lecture/écriture, <literal>c</literal> pour lecture/écriture, et
       création si la base n'existe pas, et <literal>n</literal> pour
       création, écrasement et accès en lecture/écriture.
       La base de données est créée en mode BTree ; les autres modes (comme Hash ou
       Queue) ne sont pas supportés.
      </para>
      <para>
       De plus, vous pouvez choisir la méthode de verrouillage de la base avec le 
       caractère suivant. Utilisez <literal>l</literal> pour verrouiller la base avec un 
       fichier <filename>.lck</filename>, ou <literal>d</literal> pour verrouiller
       la base elle-même. Il est important que vos application utilisent ces
       options de manière cohérente.
      </para>
      <para>
       Si vous voulez tester la possibilité d'accès, et ne pas attendre la
       disponibilité du verrou, vous pouvez ajouter la lettre <literal>t</literal>
       comme troisième caractère. Lorsque vous êtes absolument certain que votre base
       ne requière pas de verrou, vous pouvez utiliser le tiret <literal>-</literal>
       à la place de <literal>l</literal> ou <literal>d</literal>. 
       Lorsque vous n'utilisez ni <literal>d</literal>, ni <literal>l</literal> ni 
       <literal>-</literal>, dba va verrouiller en mode <literal>d</literal>.
      </para>
      <note>
       <para>
        Il ne peut y avoir qu'un seul type d'écriture dans la base. Lorsque vous
        utilisez dba sur un serveur web, et que plusieurs requêtes HTTP effectuent
        des écritures, elles ne peuvent être faites que l'une après l'autre. De même,
        la lecture durant l'écriture n'est pas possible. L'extension dba utilise
        un verrou pour éviter ces problèmes. Voici la table de verrouillage :
        <table>
         <title>Verrouillage DBA</title>
         <tgroup cols="9">
          <thead>
           <row>
            <entry>déjà ouverte</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>non-ouverte</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>attente</entry>
            <entry>&false;</entry>
            <entry>illégal</entry>
            <entry>illégal</entry>
            <entry>illégal</entry>
            <entry>illégal</entry>
           </row>
           <row>
            <entry><parameter>mode</parameter> = "wl"</entry>
            <entry>attente</entry>
            <entry>&false;</entry>
            <entry>attente</entry>
            <entry>&false;</entry>
            <entry>illégal</entry>
            <entry>illégal</entry>
            <entry>illégal</entry>
            <entry>illégal</entry>
           </row>
           <row>
            <entry><parameter>mode</parameter> = "rd"</entry>
            <entry>illégal</entry>
            <entry>illégal</entry>
            <entry>illégal</entry>
            <entry>illégal</entry>
            <entry>ok</entry>
            <entry>ok</entry>
            <entry>attente</entry>
            <entry>&false;</entry>
           </row>
           <row>
            <entry><parameter>mode</parameter> = "wd"</entry>
            <entry>illégal</entry>
            <entry>illégal</entry>
            <entry>illégal</entry>
            <entry>illégal</entry>
            <entry>attente</entry>
            <entry>&false;</entry>
            <entry>attente</entry>
            <entry>&false;</entry>
           </row>
          </tbody>
         </tgroup>
        </table>
        <simplelist>
         <member>ok: Le second appel réussit.</member>
         <member>wait: Le  second appel attend que <function>dba_close</function>
          soit appelé par le premier script.</member>
         <member>false: Le second appel retourne &false;.</member>
         <member>illégal: vous ne devez pas mélanger les options
          <literal>"l"</literal> et <literal>"d"</literal> pour le paramètre
          <parameter>mode</parameter>.</member>
        </simplelist>
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>handler</parameter></term>
     <listitem>
      <para>
       Le nom du <link linkend="dba.requirements">gestionnaire</link> 
       qui doit être utilisé pour accéder à <parameter>path</parameter>. 
       C'est passé à tous les paramètres facultatifs donnés à 
       <function>dba_open</function> et peut agir au nom d'eux.
       Si le paramètre <parameter>handler</parameter> est &null;,
       alors le gestionnaire par défaut est invoqué.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>permission</parameter></term>
     <listitem>
      <para>
       Paramètre facultatif de type &integer; qui est passé au pilote. Il a la même signification que
       le paramètre <parameter>permissions</parameter> de la fonction <function>chmod</function>,
       et a une valeur par défaut de <literal>0644</literal>.
      </para>
      <para>
       Les pilotes <literal>db1</literal>, <literal>db2</literal>,
       <literal>db3</literal>, <literal>db4</literal>, <literal>dbm</literal>,
       <literal>gdbm</literal>,
       Les pilotes <literal>ndbm</literal> et <literal>lmdb</literal> prennent en charge le
       paramètre <parameter>permission</parameter>.
      </para>
      <para>
       Le pilote <literal>lmdb</literal> supporte deux paramètres additionels.
       Le premier permet de définir le <literal>$filemode</literal>
       (voir description ci-dessus), et le second permet de définir la
       <literal>$mapsize</literal>, dont la valeur devrait être un multiple de
       la taille de page du système d'exploitation, ou zéro pour utiliser la
       mapsize par défaut.
       La paramètre <literal>$mapsize</literal> est supporté à partir de
       PHP 7.3.14 et 7.4.2, respectivement.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>map_size</parameter></term>
     <listitem>
      <para>
       Paramètre facultatif de type &integer; qui est passé au pilote. Sa valeur doit être un multiple de la
       taille de page du système d'exploitation, ou zéro pour utiliser la taille de mappage par défaut.
      </para>
      <para>
       Seul le pilote <literal>lmdb</literal> accepte le paramètre <parameter>map_size</parameter>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <para>
       Drapeaux à passer aux pilotes de base de données. Si &null;, les drapeaux par défaut seront fournis.
       Actuellement, seul le pilote LMDB prend en charge les drapeaux suivants :
       <constant>DBA_LMDB_USE_SUB_DIR</constant> et
       <constant>DBA_LMDB_NO_SUB_DIR</constant>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   &false; est retourné et une erreur de niveau <constant>E_WARNING</constant> est émise lorsque
   le paramètre <parameter>handler</parameter> est &null;, mais qu'aucun gestionnaire par défaut n'est disponible.
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Retourne une instance <classname>Dba\Connection</classname> en cas de succès&return.falseforfailure;.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.4.0</entry>
      <entry>
       Retourne désormais une instance de <classname>Dba\Connection</classname>;
       auparavant, une &resource; était retournée.
      </entry>
     </row>
     <row>
      <entry>8.2.0</entry>
      <entry>
       Le paramètre <parameter>flags</parameter> est ajouté.
      </entry>
     </row>
     <row>
      <entry>8.2.0</entry>
      <entry>
       Le paramètre <parameter>handler</parameter> est désormais nullable.
      </entry>
     </row>
     <row>
      <entry>7.3.14, 7.4.2</entry>
      <entry>
       Le pilote <literal>lmdb</literal> supporte désormais un paramètre
       additionel <parameter>map_size</parameter>.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>dba_popen</function></member>
    <member><function>dba_close</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
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/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
-->