<?xml version="1.0" encoding="iso-8859-1"?>
<reference id="ref.dba">
  <title>Funciones de la capa de abstraccion de bases de datos (dbm-style)</title>
  <titleabbrev>dba</titleabbrev>

  <partintro>
   <para>
    Estas funciones son la base para el acceso a bases de datos del estilo 
    Berkeley DB.</para>

   <para>
    Este es un nivel de abstraccion general para varias bases de datos. Como tal
    su funcionalidad esta limitada a un grupo de modernas bases de datos como 
    <ulink url="">Sleepycat Software's DB2</ulink>. (Esta no debe confundirse
    con IBM DB2 software, la cual es soportada mediante las funciones
    <link linkend="ref.odbc">ODBC</link>.)</para>


   <para>
    El comportamiento de varios aspectos depende de la implementacion de la
    base de datos. Funciones como <function>dba_optimize</function> y 
    <function>dba_sync</function> cumpliran su funcionalidad con unas bases
    de datos pero no con otras.</para>

   <para>
    Los siguientes manejadores (handlers) estan soportados:

    <itemizedlist>
     <listitem><simpara>
     dbm es el mas antiguo (original) tipo de base de datos de la familia de
     Berkeley DB. Se debe evitar su uso, si es posible. Nosotros no soportamos
     las funciones de compatibilidad de DB2 y gdbm, porque ellas solo son
     compatibles a nivel de codigo fuente, pero no pueden manejar el formato
     original dbm.</simpara></listitem>
      
     <listitem><simpara>
      ndbm es un tipo mas nuevo y mas flexible que dbm. Todavia tiene la mayoria
      de las limitaciones de dbm (Por lo tanto es descartado).</simpara></listitem>


     <listitem><simpara>
      gdbm es el gestor de bases de datos de <ulink url="">GNU (database manager)</ulink>.
     </simpara></listitem>

     <listitem><simpara>
      db2 es <ulink url="">Sleepycat Software's DB2</ulink>. Es descrito como
      "un conjunto de herramientas de programacion que proveen acceso de alto
      nivel a bases de datos en aplicaciones standalone o en el modelo cliente/servidor.
      "</simpara></listitem>
 
     
     <listitem><simpara>
      cdb es "una rapida, de confianza, sencilla herramienta para la creacion y lectura de 
      bases de datos constantes." Fue creada por el autor de qmail y puede encontrarse en
      <ulink url="">here</ulink>. Como la base es constante solo se soportan las
      operaciones de lectura.</simpara></listitem>

    </itemizedlist></para>

   <para>
    <example>
     <title>Ejemplo de DBA</title>
     <programlisting>
&lt;?php

$id = dba_open("/tmp/test.db", "n", "db2");

if(!$id) {
    echo "dba_open failed\n";
    exit;
}

dba_replace("key", "This is an example!", $id);

if(dba_exists("key", $id)) {
    echo dba_fetch("key", $id);
    dba_delete("key", $id);
}

dba_close($id);
?&gt;
</programlisting></example></para>

   <para>
    DBA es "binary safe" y no tiene ningun limite arbitrario. Hereda todas sus limitaciones
    de la implementacion de base de datos que tenga. </para>

   <para>
    Todos las bases de datos basadas en ficheros deben proveer un mecanismo para establecer
    el modo a la hora de crear nuevas bases de datos, si ello es posible. Habitualmente este modo
    es pasado como el cuarto argumento en <function>dba_open</function> o en 
    <function>dba_popen</function>.</para>

   <para>
    Se puede acceder a todas las entradas de una base de datos de modo secuencial (lineal) usando 
    las funciones <function>dba_firstkey</function> y <function>dba_nextkey</function>. No se puede
    cambiar la base de datos mientras se recorre (traversing) por ella. </para>
    
   <para>
    <example>
     <title>Recorriendo una base de datos</title>
     <programlisting>
&lt;?php

# ...open database...

$key = dba_firstkey($id);

while($key != false) {
    if(...) { # remember the key to perform some action later
        $handle_later[] = $key;
    }
    $key = dba_nextkey($id);
}

for($i = 0; $i &lt; count($handle_later); $i++)
    dba_delete($handle_later[$i], $id);

?&gt;
	 </programlisting>
	</example>
   </para>

  </partintro>

  <refentry id="function.dba-close">
   <refnamediv>
    <refname>dba_close</refname>
    <refpurpose>Cerrar uba base de datos</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripcion</title>
     <methodsynopsis>
     <type>void</type><methodname>dba_close</methodname>
     <methodparam><type>int</type><parameter>handle</parameter></methodparam>
     </methodsynopsis>

    <para>
     <function>dba_close</function> cierra la conexion con una base de datos
     previamente abierta y libera todos los recursos especificados por
     <parameter>handle</parameter>.</para>

    <para>
     <parameter>handle</parameter> es un manejador (handle) de la base de datos
     devuelto por <function>dba_open</function>.</para>

    <para>
     <function>dba_close</function> no devuelve ningun valor.</para>

    <para>
     Ver tambien:
     <function>dba_open</function>
     <function>dba_popen</function>
	</para>
     
   </refsect1>
  </refentry>

  <refentry id="function.dba-delete">
   <refnamediv>
    <refname>dba_delete</refname>
    <refpurpose>Borra una entrada especificada por la clave key</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripcion</title>
     <methodsynopsis>
     <type>bool</type><methodname>dba_delete</methodname>
     <methodparam><type>string</type><parameter>key</parameter></methodparam>
     <methodparam><type>int</type><parameter>handle</parameter></methodparam>
     </methodsynopsis>

    <para>
     <function>dba_delete</function> borra la entrada especificada por
     <parameter>key</parameter> de la base de datos especificada por 
     <parameter>handle</parameter>.</para>

    <para>
     <parameter>key</parameter> es la clave de la entrada que es borrada.</para>

    <para>
     <parameter>handle</parameter> es un manejador (handle) de la base de datos 
     devuelto por <function>dba_open</function>.</para>

    <para>
     <function>dba_delete</function> devuelve &true; o &false;, si la entrada es borrada
     o no, respectivamente.</para>

    <para>
     Ver tambien:
     <function>dba_exists</function>
     <function>dba_fetch</function>
     <function>dba_insert</function>
     <function>dba_replace</function>
	</para>
     
   </refsect1>
  </refentry>

  <refentry id="function.dba-exists">
   <refnamediv>
    <refname>dba_exists</refname>
    <refpurpose>Comprueba si la clave key existe</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripcion</title>
     <methodsynopsis>
     <type>bool</type><methodname>dba_exists</methodname>
     <methodparam><type>string</type><parameter>key</parameter></methodparam>
     <methodparam><type>int</type><parameter>handle</parameter></methodparam>
     </methodsynopsis>

    <para>
     <function>dba_exists</function> comprueba si la clave <parameter>key</parameter> 
     existe en la base de datos especificada por <parameter>handle</parameter>.</para>

    <para>
     <parameter>key</parameter> es la clave para la que se realiza la comprobacion.</para>

    <para>
     <parameter>handle</parameter> es un manejador (handle) de la base de datos
     devuelto por <function>dba_open</function>.</para>

    <para>
     <function>dba_exists</function> devuelve &true; o &false;, si la clave es hallada
     o no, respectivamente.</para>

    <para>
     Ver tambien:
     <function>dba_fetch</function>
     <function>dba_delete</function>
     <function>dba_insert</function>
     <function>dba_replace</function>
	</para>
     
   </refsect1>
  </refentry>

  <refentry id="function.dba-fetch">
   <refnamediv>
    <refname>dba_fetch</refname>
    <refpurpose>Extrae los datos especificados por la clave key</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripcion</title>
     <methodsynopsis>
     <type>string</type><methodname>dba_fetch</methodname>
     <methodparam><type>string</type><parameter>key</parameter></methodparam>
     <methodparam><type>int</type><parameter>handle</parameter></methodparam>
     </methodsynopsis>

    <para>
     <function>dba_fetch</function> extrae los datos especificados por la clave
     <parameter>key</parameter> de la base de datos determinada por
     <parameter>handle</parameter>.</para>

    <para>
     <parameter>key</parameter> es la clave de la entrada de los datos que queremos extraer.</para>

    <para>
     <parameter>handle</parameter> es un manejador (handle) de la base de datos
     devuelto por <function>dba_open</function>.</para>

    <para>
     <function>dba_fetch</function> devuelve la cadena asociada o &false;, si el
     par key/data es hallado o no, respectivamente.</para>

    <para>
     Ver tambien:
     <function>dba_exists</function>
     <function>dba_delete</function>
     <function>dba_insert</function>
     <function>dba_replace</function>
	</para>
     
   </refsect1>
  </refentry>
  <refentry id="function.dba-firstkey">
   <refnamediv>
    <refname>dba_firstkey</refname>
    <refpurpose>Conseguir la primera clave</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripcion</title>
     <methodsynopsis>
     <type>string</type><methodname>dba_firstkey</methodname>
     <methodparam><type>int</type><parameter>handle</parameter></methodparam>
     </methodsynopsis>

    <para>
     <function>dba_firstkey</function> devuelve la primera clave de la base
     de datos especificada por <parameter>handle</parameter> y resetea el puntero
     interno de claves. Esto permite una busqueda lineal por toda la base de datos.</para>

    <para>
     <parameter>handle</parameter> es un manejador (handle) de la base de datos
     devuelto por <function>dba_open</function>.</para>

    <para>
     <function>dba_firstkey</function> devuelve la clave o &false; en funcion de si
     tiene exito o falla, respectivamente.</para>

    <para>
     Ver tambien:
     <function>dba_nextkey</function>
	</para>
     
   </refsect1>
  </refentry>

  <refentry id="function.dba-insert">
   <refnamediv>
    <refname>dba_insert</refname>
    <refpurpose>Insertar una entrada</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripcion</title>
     <methodsynopsis>
     <type>bool</type><methodname>dba_insert</methodname>
     <methodparam><type>string</type><parameter>key</parameter></methodparam>
     <methodparam><type>string</type><parameter>value</parameter></methodparam>
     <methodparam><type>int</type><parameter>handle</parameter></methodparam>
     </methodsynopsis>

    <para>
     <function>dba_insert</function> inserta la entrada descrita con
     <parameter>key</parameter> y <parameter>value</parameter> dentro de la base
     de datos especificada por <parameter>handle</parameter>. Fallara si ya existe 
     una entrada con el mismo parametro <parameter>key</parameter>.</para>

    <para>
     <parameter>key</parameter> es la clave de la entrada a ser insertada.</para>

    <para>
     <parameter>value</parameter> es el valor a ser insertado.</para>

    <para>
     <parameter>handle</parameter> es un manejador (handle) de la base de datos
     devuelto por <function>dba_open</function>.</para>

    <para>
     <function>dba_insert</function> devuelve &true; o &false;, en funcion de si
     tiene exito o falla, respectivamente.</para>

    <para>
     Ver tambien:
     <function>dba_exists</function>
     <function>dba_delete</function>
     <function>dba_fetch</function>
     <function>dba_replace</function>
	</para>
     
   </refsect1>
  </refentry>

  <refentry id="function.dba-nextkey">
   <refnamediv>
    <refname>dba_nextkey</refname>
    <refpurpose>Extraer la siguiente clave</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripcion</title>
     <methodsynopsis>
     <type>string</type><methodname>dba_nextkey</methodname>
     <methodparam><type>int</type><parameter>handle</parameter></methodparam>
     </methodsynopsis>

    <para>
     <function>dba_nextkey</function> devuelve la siguiente clave de la 
     base de datos especificada por <parameter>handle</parameter> e incrementa
     el puntero de claves interno.</para>

    <para>
     <parameter>handle</parameter> es un manejador (handle) de la base de datos
     devuelto por <function>dba_open</function>.</para>

    <para>
     <function>dba_nextkey</function> devuelve la clave o &false; dependiendo de
     si tiene exito o falla, respectivamente.</para>

    <para>
     Ver tambien:
     <function>dba_firstkey</function>
	</para>
     
   </refsect1>
  </refentry>

  <refentry id="function.dba-popen">
   <refnamediv>
    <refname>dba_popen</refname>
    <refpurpose>Apertura persistente de una base de datos</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripcion</title>
     <methodsynopsis>
     <type>int</type><methodname>dba_popen</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_popen</function> establece una instancia persistente para
     <parameter>path</parameter> con <parameter>mode</parameter> usando
     <parameter>handler</parameter>.</para>

    <para>
     <parameter>path</parameter> normalmente es el "path" en el sistema de
     ficheros.</para>

    <para>
    <parameter>mode</parameter> es "r" para acceso de lectura, "w" para
    lectura/escritura de una base de datos ya existente, "c" para lectura/escritura
    y creacion de una base datos si esta no existe, y "n" para crear,
    truncar y lectura/escritura.</para>


    <para>
     <parameter>handler</parameter> es el nombre del manejador (handler)
     que sera usado para el acceso al <parameter>path</parameter>. Es pasado
     como un parametro opcional a <function>dba_popen</function> y puede
     usarse en lugar de ella.</para>

    <para>
     <function>dba_popen</function> devuelve un valor positivo de handler
     o &false;, en el caso de que la apertura de la base de datos se
     realice o si falla, respectivamente.</para>

    <para>
     Ver tambien:
     <function>dba_open</function>
     <function>dba_close</function>
	</para>
     
   </refsect1>
  </refentry>

  <refentry id="function.dba-open">
   <refnamediv>
    <refname>dba_open</refname>
    <refpurpose>Abrir una base de datos</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripcion</title>
     <methodsynopsis>
     <type>int</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> establece una instancia para
     <parameter>path</parameter> con <parameter>mode</parameter> usando
     <parameter>handler</parameter>.</para>

    <para>
     <parameter>path</parameter> normalmente es el "path" en el sistema de 
     ficheros.</para>

    <para>
     <parameter>mode</parameter> es "r" para acceso de lectura, "w" para 
     lectura/escritura de una base de datos ya existente, "c" para lectura/escritura
     y creacion de una base datos si esta no existe, y "n" para crear,
     truncar y lectura/escritura.</para>

    <para>
     <parameter>handler</parameter> es el nombre de el manejador (handler)
     que sera usado para el acceso al <parameter>path</parameter>. Es pasado
     como un parametro opcional a <function>dba_open</function> y puede 
     usarse en lugar de ella.</para>

    <para>
     <function>dba_open</function> devuelve un valor positivo de handler 
      o &false;, en el caso de que la apertura de la base de datos se
      realice o si falla, respectivamente.</para>

    <para>
     Ver tambien:
     <function>dba_popen</function>
     <function>dba_close</function>
	</para>
     
   </refsect1>
  </refentry>

  <refentry id="function.dba-optimize">
   <refnamediv>
    <refname>dba_optimize</refname>
    <refpurpose>Optimiza la base de datos</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripcion</title>
     <methodsynopsis>
     <type>bool</type><methodname>dba_optimize</methodname>
     <methodparam><type>int</type><parameter>handle</parameter></methodparam>
     </methodsynopsis>

    <para>
     <function>dba_optimize</function> optimiza la base de datos especificada
     por <parameter>handle</parameter>.</para>

    <para>
     <parameter>handle</parameter> es un manejador (handle) de la base de datos
     devuelto por <function>dba_open</function>.</para>

    <para>
     <function>dba_optimize</function> devuelve &true; o &false;, si la 
     optimizacion tiene exito o falla, respectivamente.</para>

    <para>
     Ver tambien:
     <function>dba_sync</function>
	</para>
     
   </refsect1>
  </refentry>

  <refentry id="function.dba-replace">
   <refnamediv>
    <refname>dba_replace</refname>
    <refpurpose>Reemplaza o inserta una entrada</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripcion</title>
     <methodsynopsis>
     <type>bool</type><methodname>dba_replace</methodname>
     <methodparam><type>string</type><parameter>key</parameter></methodparam>
     <methodparam><type>string</type><parameter>value</parameter></methodparam>
     <methodparam><type>int</type><parameter>handle</parameter></methodparam>
     </methodsynopsis>

    <para>
     <function>dba_replace</function> reemplaza o inserta la entrada descrita
     con <parameter>key</parameter> y <parameter>value</parameter> dentro de la
     base de datos especificada por <parameter>handle</parameter>.</para> 

    <para>
     <parameter>key</parameter> es la clave de la entrada a insertar.</para>

    <para>
     <parameter>value</parameter> es el valor a ser insertado.</para>

    <para>
     <parameter>handle</parameter> es un manejador (handle) de la base de datos
     devuelto por <function>dba_open</function>.</para>

    <para>
     <function>dba_replace</function> devuelve &true; o &false;, dependiendo de
     si tiene exito o falla respectivamente.</para>

    <para>
     Ver tambien:
     <function>dba_exists</function>
     <function>dba_delete</function>
     <function>dba_fetch</function>
     <function>dba_insert</function>
	</para>
     
   </refsect1>
  </refentry>

  <refentry id="function.dba-sync">
   <refnamediv>
    <refname>dba_sync</refname>
    <refpurpose>Sincroniza la base de datos</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripcion</title>
     <methodsynopsis>
     <type>bool</type><methodname>dba_sync</methodname>
     <methodparam><type>int</type><parameter>handle</parameter></methodparam>
     </methodsynopsis>

    <para>
     <function>dba_sync</function> sincroniza la base de datos especificada por
     <parameter>handle</parameter>. Esto probablemente realice una escritura fisica
     en el disco, si es soportado.</para>

    <para>
     <parameter>handle</parameter> es un manejador (handle) de la base de datos
      devuelto por <function>dba_open</function>.</para>

    <para>
     <function>dba_sync</function> devuelve &true; o &false;, si la 
     sincronizacion tiene exito o falla, respectivamente.</para>

    <para>
     Ver tambien:
     <function>dba_optimize</function>
	</para>
     
   </refsect1>
  </refentry>
 </reference>

<!-- 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:
-->