<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.17 $ -->
 <reference id="ref.dbase">
  <title>dBase functions</title>
  <titleabbrev>dBase</titleabbrev>

  <partintro>
   <simpara>
    These functions allow you to access records stored in dBase-format
    (dbf) databases.  In order to use these functions, you must compile
    PHP with the <option role="configure">--enable-dbase</option> option.
   </simpara>
   <simpara>
    There is no support for indexes or memo fields. There is no
    support for locking, too. Two concurrent webserver processes
    modifying the same dBase file will very likely ruin your database.
   </simpara>
   <simpara>
    dBase files are simple sequential files of fixed
    length records. Records are appended to the end of
    the file and delete records are kept until you call
    <function>dbase_pack</function>.
   </simpara>
   <simpara>
    We recommend that you do not use dBase files as your production
    database. Choose any real SQL server instead; MySQL or Postgres
    are common choices with PHP. dBase support is here to allow you to
    import and export data to and from your web database, because the
    file format is commonly understood by Windows spreadsheets and
    organizers.
   </simpara>
  </partintro>

  <refentry id="function.dbase-create">
   <refnamediv>
    <refname>dbase_create</refname>
    <refpurpose>Creates a dBase database</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>dbase_create</methodname>
      <methodparam><type>string</type><parameter>filename</parameter></methodparam>
      <methodparam><type>array</type><parameter>fields</parameter></methodparam>
     </methodsynopsis>
    <para>
     The <parameter>fields</parameter> parameter is an array of
     arrays, each array describing the format of one field in the
     database. Each field consists of a name, a character indicating
     the field type, a length, and a precision.
    </para>
    <para>
     The types of fields available are:
     <variablelist>
      <varlistentry>
       <term>L</term>
       <listitem>
        <simpara>
         Boolean. These do not have a length or precision.
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>M</term>
       <listitem>
        <simpara>
         Memo. (Note that these aren't supported by PHP.)  These do
         not have a length or precision.
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>D</term>
       <listitem>
        <simpara>
         Date (stored as YYYYMMDD).  These do not have a length or
         precision.
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>N</term>
       <listitem>
        <simpara>
         Number. These have both a length and a precision (the number
         of digits after the decimal point).
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>C</term>
       <listitem>
        <simpara>
         String.
        </simpara>
       </listitem>
      </varlistentry>
     </variablelist>
    </para>
    <para>
     If the database is successfully created, a dbase_identifier is
     returned, otherwise &false; is returned.
     <example>
      <title>Creating a dBase database file</title>
      <programlisting role="php">
<![CDATA[
// "database" name
$dbname = "/tmp/test.dbf";

// database "definition"
$def =
    array(
        array("date",     "D"),
        array("name",     "C",  50),
        array("age",      "N",   3, 0),
        array("email",    "C", 128),
        array("ismember", "L")
    );

// creation
if (!dbase_create($dbname, $def))
    print "<strong>Error!</strong>";
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dbase-open">
   <refnamediv>
    <refname>dbase_open</refname>
    <refpurpose>Opens a dBase database</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>dbase_open</methodname>
      <methodparam><type>string</type><parameter>filename</parameter></methodparam>
      <methodparam><type>int</type><parameter>flags</parameter></methodparam>
     </methodsynopsis>
    <para>
     The flags correspond to those for the open() system call.
     (Typically 0 means read-only, 1 means write-only, and 2 means
     read and write.)
    </para>
    <para>
     Returns a dbase_identifier for the opened database, or &false; if
     the database couldn't be opened.
    </para>
    &note.sm.uidcheck;
   </refsect1>
  </refentry>

  <refentry id="function.dbase-close">
   <refnamediv>
    <refname>dbase_close</refname>
    <refpurpose>Close a dBase database</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>dbase_close</methodname>
      <methodparam><type>int</type><parameter>dbase_identifier</parameter></methodparam>
     </methodsynopsis>
    <para>
     Closes the database associated with
     <parameter>dbase_identifier</parameter>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dbase-pack">
   <refnamediv>
    <refname>dbase_pack</refname>
    <refpurpose>Packs a dBase database</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>dbase_pack</methodname>
      <methodparam><type>int</type><parameter>dbase_identifier</parameter></methodparam>
     </methodsynopsis>
    <para>
     Packs the specified database (permanently deleting all records
     marked for deletion using
     <function>dbase_delete_record</function>).
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dbase-add-record">
   <refnamediv>
    <refname>dbase_add_record</refname>
    <refpurpose>Add a record to a dBase database</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>dbase_add_record</methodname>
      <methodparam><type>int</type><parameter>dbase_identifier</parameter></methodparam>
      <methodparam><type>array</type><parameter>record</parameter></methodparam>
     </methodsynopsis>
    <para>
     Adds the data in the <parameter>record</parameter> to the
     database. If the number of items in the supplied record isn't
     equal to the number of fields in the database, the operation will
     fail and &false; will be returned.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dbase-replace-record">
   <refnamediv>
    <refname>dbase_replace_record</refname>
    <refpurpose>Replace a record in a dBase database</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>dbase_replace_record</methodname>
      <methodparam><type>int</type><parameter>dbase_identifier</parameter></methodparam>
      <methodparam><type>array</type><parameter>record</parameter></methodparam>
      <methodparam><type>int</type><parameter>dbase_record_number</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     Replaces the data associated with the record
     <parameter>record_number</parameter> with the data in the
     <parameter>record</parameter> in the database. If the number of
     items in the supplied record is not equal to the number of fields
     in the database, the operation will fail and &false; will be
     returned.
    </simpara>
    <simpara>
     <parameter>dbase_record_number</parameter> is an integer which
     spans from 1 to the number of records in the database (as
     returned by <function>dbase_numrecords</function>).
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.dbase-delete-record">
   <refnamediv>
    <refname>dbase_delete_record</refname>
    <refpurpose>Deletes a record from a dBase database</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>dbase_delete_record</methodname>
      <methodparam><type>int</type><parameter>dbase_identifier</parameter></methodparam>
      <methodparam><type>int</type><parameter>record</parameter></methodparam>
     </methodsynopsis>
    <para>
     Marks <parameter>record</parameter> to be deleted from the
     database.  To actually remove the record from the database, you
     must also call <function>dbase_pack</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dbase-get-record">
   <refnamediv>
    <refname>dbase_get_record</refname>
    <refpurpose>Gets a record from a dBase database</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>dbase_get_record</methodname>
      <methodparam><type>int</type><parameter>dbase_identifier</parameter></methodparam>
      <methodparam><type>int</type><parameter>record</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the data from <parameter>record</parameter> in an
     array. The array is indexed starting at 0, and includes an
     associative member named 'deleted' which is set to 1 if the
     record has been marked for deletion (see
     <function>dbase_delete_record</function>.
    </para>
    <para>
     Each field is converted to the appropriate PHP type, except:
     <itemizedlist>
      <listitem>
       <simpara>
        Dates are left as strings
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        Integers that would have caused an overflow (> 32 bits)
        are returned as strings
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dbase-get-record-with-names">
   <refnamediv>
    <refname>dbase_get_record_with_names</refname>
    <refpurpose>
     Gets a record from a dBase database as an associative array
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>dbase_get_record_with_names</methodname>
      <methodparam><type>int</type><parameter>dbase_identifier</parameter></methodparam>
      <methodparam><type>int</type><parameter>record</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the data from <parameter>record</parameter> in an
     associative array.  The array also includes an associative member
     named 'deleted' which is set to 1 if the record has been marked
     for deletion (see <function>dbase_delete_record</function>).
    </para>
    <para>
     Each field is converted to the appropriate PHP type, except:
     <itemizedlist>
      <listitem>
       <simpara>
        Dates are left as strings
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        Integers that would have caused an overflow (> 32 bits)
        are returned as strings
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dbase-numfields">
   <refnamediv>
    <refname>dbase_numfields</refname>
    <refpurpose>
     Find out how many fields are in a dBase database
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>dbase_numfields</methodname>
      <methodparam><type>int</type><parameter>dbase_identifier</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the number of fields (columns) in the specified
     database. Field numbers are between 0 and dbase_numfields($db)-1,
     while record numbers are between 1 and dbase_numrecords($db).
     <example>
      <title>Using <function>dbase_numfields</function></title>
      <programlisting role="php">
<![CDATA[
$rec = dbase_get_record($db, $recno);
$nf  = dbase_numfields($db);
for ($i=0; $i < $nf; $i++) {
    print $rec[$i]."<br>\n";
}
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dbase-numrecords">
   <refnamediv>
    <refname>dbase_numrecords</refname>
    <refpurpose>
     Find out how many records are in a dBase database
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>dbase_numrecords</methodname>
      <methodparam><type>int</type><parameter>dbase_identifier</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the number of records (rows) in the specified
     database. Record numbers are between 1 and dbase_numrecords($db),
     while field numbers are between 0 and dbase_numfields($db)-1.
    </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:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->