cvs: peardoc /en/pecl paradox.xml
| From: | Uwe Steinmann | Date: | Fri, 31 Oct 2003 14:54:39 +0000 |
| Subject: | cvs: peardoc /en/pecl paradox.xml | ||
| Groups: | php.pear.doc | ||
| Request: | Send a blank email to pear-doc+get-1839@lists.php.net to get a copy of this message | ||
steinm Fri Oct 31 09:54:39 2003 EDT
Modified files:
/peardoc/en/pecl paradox.xml
Log:
- major update, all functions are now documented, several examples added, cross references added
Index: peardoc/en/pecl/paradox.xml diff -u peardoc/en/pecl/paradox.xml:1.2 peardoc/en/pecl/paradox.xml:1.3 --- peardoc/en/pecl/paradox.xml:1.2 Sat Sep 13 15:42:51 2003 +++ peardoc/en/pecl/paradox.xml Fri Oct 31 09:54:39 2003 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.2 $ --> +<!-- $Revision: 1.3 $ --> <!-- Author: Uwe Steinmann <steinm@php.net> --> <reference id="pecl.paradox"> <title>Paradox File Access</title> @@ -7,22 +7,175 @@ <partintro> <sect1 id="pecl.paradox.partintro"> <title>Introduction</title> + <sect2 id="pecl.paradox.intro"> <title>About Paradox file access</title> <para> - This module allows to read Paradox database and blob files. + This module allows to read Paradox database and primary index files. + It has initial support for creating Paradox databases. Consider it + to be experimental due to lack of documentation of the Paradox file + format. </para> <note> <para> You will need to get the paradox library (libpx) available at - http://pxlib.sourceforge.net. + <ulink url="http://pxlib.sourceforge.net">http://pxlib.sourceforge.net</ulink>. </para> + </note> + <note> <para> This module has not been tested on other platforms than Debian/GNU Linux for PPC. </para> </note> + <note> + <para> + This module is also in development and may change, though I don't + expect major changes to the API. + </para> + </note> + </sect2> + + <sect2 id="pecl.paradox.constants"> + <title>Constants</title> + <para> + The following two tables lists all constants defined by the paradox + extension. + + <table id="pecl.paradox.table-fieldtypes"> + <title>Contants for field types</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Name</entry> + <entry>Meaning</entry> + </row> + </thead> + <tbody> + <row> + <entry>PX_FIELD_ALPHA</entry> + <entry>Character data with fixed length</entry> + </row> + <row> + <entry>PX_FIELD_DATE</entry> + <entry>Date</entry> + </row> + <row> + <entry>PX_FIELD_SHORT</entry> + <entry>Short integer (2 Bytes)</entry> + </row> + <row> + <entry>PX_FIELD_LONG</entry> + <entry>Long integer (4 Bytes)</entry> + </row> + <row> + <entry>PX_FIELD_CURRENCY</entry> + <entry>same as PX_FIELD_NUMBER</entry> + </row> + <row> + <entry>PX_FIELD_NUMBER</entry> + <entry>Double</entry> + </row> + <row> + <entry>PX_FIELD_LOGICAL</entry> + <entry>Boolean</entry> + </row> + <row> + <entry>PX_FIELD_MEMOBLOB</entry> + <entry>Binary large object (not supported)</entry> + </row> + <row> + <entry>PX_FIELD_BLOB</entry> + <entry>Binary large object (not supported)</entry> + </row> + <row> + <entry>PX_FIELD_FMTMEMOBLOB</entry> + <entry>Binary large object (not supported)</entry> + </row> + <row> + <entry>PX_FIELD_OLE</entry> + <entry>OLE object (basically a blob, not supported)</entry> + </row> + <row> + <entry>PX_FIELD_GRAPHIC</entry> + <entry>Graphic (basically a blob, not supported)</entry> + </row> + <row> + <entry>PX_FIELD_TIME</entry> + <entry>time</entry> + </row> + <row> + <entry>PX_FIELD_TIMESTAMP</entry> + <entry>timestamp (like the unix timestamp)</entry> + </row> + <row> + <entry>PX_FIELD_AUTOINC</entry> + <entry>Auto incrementing interger (like PX_FIELD_LONG)</entry> + </row> + <row> + <entry>PX_FIELD_BCD</entry> + <entry>Decimal number stored in bcd format (not supported)</entry> + </row> + <row> + <entry>PX_FIELD_BYTES</entry> + <entry>Array of Bytes with not more than 255 bytes (not supported)</entry> + </row> + </tbody> + </tgroup> + </table> + + <table id="pecl.paradox.table-filetypes"> + <title>Contants for file types</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Name</entry> + <entry>Meaning</entry> + </row> + </thead> + <tbody> + <row> + <entry>PX_FILE_INDEX_DB</entry> + <entry>Indexed database</entry> + </row> + <row> + <entry>PX_FILE_PRIM_INDEX</entry> + <entry>Primary index</entry> + </row> + <row> + <entry>PX_FILE_NON_INDEX_DB</entry> + <entry>None indexed database</entry> + </row> + <row> + <entry>PX_FILE_NON_INC_SEC_INDEX</entry> + <entry>None incremental secondary index (not supported)</entry> + </row> + <row> + <entry>PX_FILE_SEC_INDEX</entry> + <entry>Secondary index (not supported)</entry> + </row> + <row> + <entry>PX_FILE_INC_SEC_INDEX</entry> + <entry>Incremental secondary index (not supported)</entry> + </row> + <row> + <entry>PX_FILE_NON_INC_SEC_INDEX_G</entry> + <entry>(not supported)</entry> + </row> + <row> + <entry>PX_FILE_SEC_INDEX_G</entry> + <entry>(not supported)</entry> + </row> + <row> + <entry>PX_FILE_INC_SEC_INDEX_G</entry> + <entry>(not supported)</entry> + </row> + </tbody> + </tgroup> + </table> + </para> </sect2> + <sect2 id="pecl.paradox.install"> <title>Installation</title> <para> @@ -30,7 +183,7 @@ <itemizedlist> <listitem> <simpara> - You need at least PHP 4.1.0 and libpx >= 0.0.9 + You need at least PHP 5.0.0 and libpx >= 0.1.9 </simpara> </listitem> <listitem> @@ -41,12 +194,98 @@ </itemizedlist> </para> </sect2> + <sect2 id="pecl.paradox.configuration"> <title>Configuration</title> <para> </para> </sect2> + + <sect2 id="pecl.paradox.oo-api"> + <title>Object oriented API</title> + <para> + The paradox extension provides also an + object oriented API. It consists of only one class called + paradox_doc. Its methods only differ from the functions + in its name and of course the missing first parameter. + The following table will list all methods and its + equivalent functions. + + <table id="pecl.paradox.table-class-methods"> + <title>Methods of class paradox_doc</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Name of method</entry> + <entry>Equivalent function</entry> + </row> + </thead> + <tbody> + <row> + <entry>Constructor</entry> + <entry><function>px_new</function></entry> + </row> + <row> + <entry>Destructor</entry> + <entry><function>px_delete</function></entry> + </row> + <row> + <entry><function>open_fp</function></entry> + <entry><function>px_open_fp</function></entry> + </row> + <row> + <entry><function>create_fp</function></entry> + <entry><function>px_create_fp</function></entry> + </row> + <row> + <entry><function>close</function></entry> + <entry><function>px_close</function></entry> + </row> + <row> + <entry><function>numrecords</function></entry> + <entry><function>px_numrecords</function></entry> + </row> + <row> + <entry><function>numfields</function></entry> + <entry><function>px_numfields</function></entry> + </row> + <row> + <entry><function>get_record</function></entry> + <entry><function>px_get_record</function></entry> + </row> + <row> + <entry><function>put_record</function></entry> + <entry><function>px_put_record</function></entry> + </row> + <row> + <entry><function>get_field</function></entry> + <entry><function>px_get_field</function></entry> + </row> + <row> + <entry><function>get_schema</function></entry> + <entry><function>px_get_schema</function></entry> + </row> + <row> + <entry><function>get_info</function></entry> + <entry><function>px_get_info</function></entry> + </row> + <row> + <entry><function>set_targetencoding</function></entry> + <entry><function>px_set_targetencoding</function></entry> + </row> + <row> + <entry><function>set_tablename</function></entry> + <entry><function>px_set_tablename</function></entry> + </row> + </tbody> + </tgroup> + </table> + + </para> + </sect2> + </sect1> + </partintro> <refentry id="pecl.paradox.px-new"> @@ -59,16 +298,65 @@ <funcsynopsis> <funcprototype> <funcdef>resource <function>px_new</function></funcdef> - <paramdef>void <parameter></parameter></paramdef> + <paramdef>void <parameter></parameter></paramdef> </funcprototype> </funcsynopsis> <para> Create a new paradox object. You will have to call this function - before any further functions. + before any further functions. <function>px_new</function> does not + create any file on the disk, it justs creates an instance of a paradox + object. Returns FALSE on failure. + </para> + <para> + <example> + <title>Opening a Paradox database</title> + <programlisting role="php"> +<![CDATA[ +<?php +if(!$pxdoc = px_new()) { + /* Error handling */ +} +$fp = fopen("test.db", "r"); +if(!px_open_fp($pxdoc, $fp)) { + /* Error handling */ +} +// ... +px_close($pxdoc); +px_delete($pxdoc); +fclose($fp); +?> +]]> + </programlisting> + </example> + </para> + <para> + If you prefer the object oriented API, then the above example will look + like the following. + <example> + <title>Opening a Paradox database</title> + <programlisting role="php"> +<![CDATA[ +<?php +$fp = fopen("test.db", "r"); +$pxdoc = new paradox_db(); +if(!$pxdoc->open_fp($fp)) { + /* Error handling */ +} +// ... +$pxdoc->close(); +fclose($fp); +?> +]]> + </programlisting> + </example> + </para> + <para> + See also <function>px_open_fp</function>, <function>px_delete</function>. </para> </refsect1> </refentry> - <refentry id="pecl.paradox.px-open-fp"> + + <refentry id="pecl.paradox.px-open-fp"> <refnamediv> <refname>px_open_fp</refname> <refpurpose>Open paradox database</refpurpose> @@ -84,12 +372,88 @@ </funcsynopsis> <para> Open an existing paradox database file. The actual file has to + be opened before with <function>fopen</function>. The first parameter + is the return value of <function>px_new</function>. This function can + also be used to open primary index files and tread them like a paradox + database. This is supported for those who would like to investigate + a primary index. It cannot be used to accelerate access to a database + file. Returns FALSE on failure. + </para> + <para> + See also example at <function>px_new</function>, <function>fopen</function>. + </para> + </refsect1> + </refentry> + + <refentry id="pecl.paradox.px-create-fp"> + <refnamediv> + <refname>px_create_fp</refname> + <refpurpose>Create a new paradox database</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>px_create_fp</function></funcdef> + <paramdef>resource <parameter>pxdoc</parameter></paramdef> + <paramdef>array <parameter>fielddesc</parameter></paramdef> + <paramdef>resource <parameter>file</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Create a new paradox database file. The actual file has to be opened before with fopen(). The first parameter is the return - value of px_new(). + value of px_new(). <option>fielddesc</option> is an array containing + one element for each field containing is specification. Each field + specification is an array itself with either two or three elements. + The first element is always a string values used as the name of field. + It may not be larger than ten characters. The second element contains + the field type which is one of the constants listed in table <link + linkend="pecl.paradox.table-fieldtypes">Constants for field types</link>. + In the case of a + character field, you will have to provide a third element specifying + the length of the field. + </para> + <note> + <para>This function is highly experimental, due to insufficient + documentation of the paradox file format. Database files created + with this function can be opened by <function>px_open_fp</function> + but probably cannot be opened by the Paradox software.</para> + </note> + <para> + <example> + <title>Creating a Paradox database with two fields</title> + <programlisting role="php"> +<![CDATA[ +<?php +if(!$pxdoc = px_new()) { + /* Error handling */ +} +$fp = fopen("test.db", "w+"); +$fields = array(array("col1", "S"), array("col2", "I")); +if(!@px_create_fp($pxdoc, $fields, $fp)) { + /* Error handling */ +} +px_set_tablename($pxdoc, "testtable"); +for($i=-50; $i<50; $i++) { + $rec = array($i, -$i); + px_put_record($pxdoc, $rec); +} +px_close($pxdoc); +px_delete($pxdoc); +fclose($fp); +?> +]]> + </programlisting> + </example> + </para> + <para> + See also <function>px_new</function>, <function>fopen</function>, + <function>px_put_record</function>. </para> </refsect1> - </refentry> + <refentry id="pecl.paradox.px-close"> <refnamediv> <refname>px_close</refname> @@ -104,10 +468,16 @@ </funcprototype> </funcsynopsis> <para> - Close the paradox database. + Close the paradox file. This function will not close the file. You will + have to call <function>fclose</function> afterwards. + </para> + <para> + See also <function>px_open_fp</function>, the example at + <function>px_new</function>. </para> </refsect1> </refentry> + <refentry id="pecl.paradox.px-delete"> <refnamediv> <refname>px_delete</refname> @@ -126,6 +496,7 @@ </para> </refsect1> </refentry> + <refentry id="pecl.paradox.px-get-record"> <refnamediv> <refname>px_get_record</refname> @@ -135,17 +506,55 @@ <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>bool <function>px_delete</function></funcdef> + <funcdef>array <function>px_get_record</function></funcdef> <paramdef>resource <parameter>pxdoc</parameter></paramdef> <paramdef>int <parameter>num</parameter></paramdef> <paramdef>int <parameter><optional>mode</optional></parameter></paramdef> </funcprototype> </funcsynopsis> <para> - Deletes the resource of the paradox file and frees all memory. + Returns the num'th record from the paradox database. The record is + returned as an associated array with its keys being the field names. + <parameter>mode</parameter> can be PX_KEYTOLOWER or PX_KEYTOUPPER + in order to convert the keys into lower or upper case. If + <parameter>mode</parameter> is not passed or is 0, then the key will be + exactly + like the field name. The element values will contain the field values. + NULL values will be retained and are different from 0.0, 0 or the empty + string. Currently only values for fields of type PX_FIELD_ALPHA, + PX_FIELD_SHORT, PX_FIELD_LONG, PX_FIELD_AUTOINC, PX_FIELD_NUMBER, + PX_FIELD_CURRENCY and PX_FIELD_LOGICAL are supported. Fields of + unsupported type will not be part of the array. This means, that + the return value of <function>px_num_fields</function> may differ + from the number of elements in the array returned by this function.</para> + <para> + The record number is an artificial number counting records in the + order as they are stored in the database. The first record has number 0. </para> </refsect1> </refentry> + + <refentry id="pecl.paradox.px-put-record"> + <refnamediv> + <refname>px_put_record</refname> + <refpurpose>Stores record into paradox database</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>px_put_record</function></funcdef> + <paramdef>resource <parameter>pxdoc</parameter></paramdef> + <paramdef>array <parameter>record</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Stores a record into a paradox database. The record is added at the + end of the database. + </para> + </refsect1> + </refentry> + <refentry id="pecl.paradox.px-numrecords"> <refnamediv> <refname>px_numrecords</refname> @@ -160,10 +569,13 @@ </funcprototype> </funcsynopsis> <para> - Returns the number of records in a database file. + Returns the number of records in a database file. The return value + of this function is identical to the element 'numrecords' in the + associated array returned by <function>px_get_info</function>. </para> </refsect1> </refentry> + <refentry id="pecl.paradox.px-numfields"> <refnamediv> <refname>px_numfields</refname> @@ -178,10 +590,13 @@ </funcprototype> </funcsynopsis> <para> - Returns the number of fields in a database file. + Returns the number of fields in a database file. The return value + of this function is identical to the element 'numfields' in the + associated array returned by <function>px_get_info</function>. </para> </refsect1> </refentry> + <refentry id="pecl.paradox.px-get-schema"> <refnamediv> <refname>px_get_schema</refname> @@ -197,14 +612,43 @@ </funcprototype> </funcsynopsis> <para> - Returns the schema of a database file. + Returns the schema of a database file as an associated array. The key + name is equal to the field name. If <parameter>mode</parameter> is + PX_KEYTOLOWER or PX_KEYTOUPPER the key will be converted to lower or + upper case. If <parameter>mode</parameter> is 0 or not passed at all, + then the key name will be identical to the field name. Each array + element is itself an associated array containing the two fields + 'type' and 'size'. 'type' is one of the constants in table <link + linkend="pecl.paradox.table-fieldtypes">Constants for field types</link>. </para> </refsect1> </refentry> + + <refentry id="pecl.paradox.px-get-field"> + <refnamediv> + <refname>px_get_field</refname> + <refpurpose>Returns the specification of a single field</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>px_get_field</function></funcdef> + <paramdef>resource <parameter>pxdoc</parameter></paramdef> + <paramdef>int <parameter><optional>fieldno</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns the specification of the fieldno'th database field as an associated + array. The array contains three fields named 'name', 'type' and 'size'. + </para> + </refsect1> + </refentry> + <refentry id="pecl.paradox.px-set-targetencoding"> <refnamediv> <refname>px_set_targetencoding</refname> - <refpurpose>Sets the encoding of the output</refpurpose> + <refpurpose>Sets the encoding for character fields</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -216,10 +660,139 @@ </funcprototype> </funcsynopsis> <para> - Set the encoding of the output. + Set the encoding data retrieved from character fields. All character + fields will be recoded + to the encoding set by this function. If the encoding is not set, the + character data will be returned in the DOS code page encoding as + specified in the database. Returns FALSE if encoding could not be set, + e.g. the encoding is unknown, or pxlib does not support recoding at all. + In the second case a warning will be issued. + </para> + <para> + See also <function>px_get_info</function> to determine the DOS code page. </para> </refsect1> </refentry> + + <refentry id="pecl.paradox.px-set-tablename"> + <refnamediv> + <refname>px_set_tablename</refname> + <refpurpose>Sets the name of a table</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>px_set_tablename</function></funcdef> + <paramdef>resource <parameter>pxdoc</parameter></paramdef> + <paramdef>string <parameter>name</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Sets the table name of a paradox database, which was created with + <function>px_create_fp</function>. Applying this function on an + existing database has no effect. + </para> + </refsect1> + </refentry> + + <refentry id="pecl.paradox.px-get-info"> + <refnamediv> + <refname>px_get_info</refname> + <refpurpose>Return lots of information about a paradox file</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>px_get_info</function></funcdef> + <paramdef>resource <parameter>pxdoc</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns an associated array with lots of information about a paradox + file. This array is likely to extend in the future. + </para> + <variablelist> + <varlistentry> + <term>fileversion</term> + <listitem> + <para>Version of file multiplied by 10. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>tablename</term> + <listitem> + <para>Name of table as stored in the the file. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>numrecords</term> + <listitem> + <para>Number of records in this database. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>numfields</term> + <listitem> + <para>Number of fields in the table. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>headersize</term> + <listitem> + <para>Number of bytes used for the header. This is usally 0x800. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>maxtablesize</term> + <listitem> + <para>This value multiplied by 0x400 is the size of a data block. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>numdatablocks</term> + <listitem> + <para>The number of data blocks in the file. Each data block contains + a certain number of records which depends on the record size and + the data block size (maxtablesize). Data blocks may not necessarily + be completely filled. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>numindexfields</term> + <listitem> + <para>Number of fields used for the primary index. The fields do + always start as field number 1. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>codepage</term> + <listitem> + <para>The DOS codepage which was used for encoding fields which + character data. If the target encoding is not set with + <function>px_set_targetencoding</function> this will be the encoding + for character fields when access records with + <function>px_get_record</function>. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + See also <function>px_numfields</function>, + <function>px_numrecords</function>. + </para> + </refsect1> + </refentry> + </reference> <!-- Keep this comment at the end of the file
Index: peardoc/en/pecl/paradox.xml diff -u peardoc/en/pecl/paradox.xml:1.2 peardoc/en/pecl/paradox.xml:1.3 --- peardoc/en/pecl/paradox.xml:1.2 Sat Sep 13 15:42:51 2003 +++ peardoc/en/pecl/paradox.xml Fri Oct 31 09:54:39 2003 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.2 $ --> +<!-- $Revision: 1.3 $ --> <!-- Author: Uwe Steinmann <steinm@php.net> --> <reference id="pecl.paradox"> <title>Paradox File Access</title> @@ -7,22 +7,175 @@ <partintro> <sect1 id="pecl.paradox.partintro"> <title>Introduction</title> + <sect2 id="pecl.paradox.intro"> <title>About Paradox file access</title> <para> - This module allows to read Paradox database and blob files. + This module allows to read Paradox database and primary index files. + It has initial support for creating Paradox databases. Consider it + to be experimental due to lack of documentation of the Paradox file + format. </para> <note> <para> You will need to get the paradox library (libpx) available at - http://pxlib.sourceforge.net. + <ulink url="http://pxlib.sourceforge.net">http://pxlib.sourceforge.net</ulink>. </para> + </note> + <note> <para> This module has not been tested on other platforms than Debian/GNU Linux for PPC. </para> </note> + <note> + <para> + This module is also in development and may change, though I don't + expect major changes to the API. + </para> + </note> + </sect2> + + <sect2 id="pecl.paradox.constants"> + <title>Constants</title> + <para> + The following two tables lists all constants defined by the paradox + extension. + + <table id="pecl.paradox.table-fieldtypes"> + <title>Contants for field types</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Name</entry> + <entry>Meaning</entry> + </row> + </thead> + <tbody> + <row> + <entry>PX_FIELD_ALPHA</entry> + <entry>Character data with fixed length</entry> + </row> + <row> + <entry>PX_FIELD_DATE</entry> + <entry>Date</entry> + </row> + <row> + <entry>PX_FIELD_SHORT</entry> + <entry>Short integer (2 Bytes)</entry> + </row> + <row> + <entry>PX_FIELD_LONG</entry> + <entry>Long integer (4 Bytes)</entry> + </row> + <row> + <entry>PX_FIELD_CURRENCY</entry> + <entry>same as PX_FIELD_NUMBER</entry> + </row> + <row> + <entry>PX_FIELD_NUMBER</entry> + <entry>Double</entry> + </row> + <row> + <entry>PX_FIELD_LOGICAL</entry> + <entry>Boolean</entry> + </row> + <row> + <entry>PX_FIELD_MEMOBLOB</entry> + <entry>Binary large object (not supported)</entry> + </row> + <row> + <entry>PX_FIELD_BLOB</entry> + <entry>Binary large object (not supported)</entry> + </row> + <row> + <entry>PX_FIELD_FMTMEMOBLOB</entry> + <entry>Binary large object (not supported)</entry> + </row> + <row> + <entry>PX_FIELD_OLE</entry> + <entry>OLE object (basically a blob, not supported)</entry> + </row> + <row> + <entry>PX_FIELD_GRAPHIC</entry> + <entry>Graphic (basically a blob, not supported)</entry> + </row> + <row> + <entry>PX_FIELD_TIME</entry> + <entry>time</entry> + </row> + <row> + <entry>PX_FIELD_TIMESTAMP</entry> + <entry>timestamp (like the unix timestamp)</entry> + </row> + <row> + <entry>PX_FIELD_AUTOINC</entry> + <entry>Auto incrementing interger (like PX_FIELD_LONG)</entry> + </row> + <row> + <entry>PX_FIELD_BCD</entry> + <entry>Decimal number stored in bcd format (not supported)</entry> + </row> + <row> + <entry>PX_FIELD_BYTES</entry> + <entry>Array of Bytes with not more than 255 bytes (not supported)</entry> + </row> + </tbody> + </tgroup> + </table> + + <table id="pecl.paradox.table-filetypes"> + <title>Contants for file types</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Name</entry> + <entry>Meaning</entry> + </row> + </thead> + <tbody> + <row> + <entry>PX_FILE_INDEX_DB</entry> + <entry>Indexed database</entry> + </row> + <row> + <entry>PX_FILE_PRIM_INDEX</entry> + <entry>Primary index</entry> + </row> + <row> + <entry>PX_FILE_NON_INDEX_DB</entry> + <entry>None indexed database</entry> + </row> + <row> + <entry>PX_FILE_NON_INC_SEC_INDEX</entry> + <entry>None incremental secondary index (not supported)</entry> + </row> + <row> + <entry>PX_FILE_SEC_INDEX</entry> + <entry>Secondary index (not supported)</entry> + </row> + <row> + <entry>PX_FILE_INC_SEC_INDEX</entry> + <entry>Incremental secondary index (not supported)</entry> + </row> + <row> + <entry>PX_FILE_NON_INC_SEC_INDEX_G</entry> + <entry>(not supported)</entry> + </row> + <row> + <entry>PX_FILE_SEC_INDEX_G</entry> + <entry>(not supported)</entry> + </row> + <row> + <entry>PX_FILE_INC_SEC_INDEX_G</entry> + <entry>(not supported)</entry> + </row> + </tbody> + </tgroup> + </table> + </para> </sect2> + <sect2 id="pecl.paradox.install"> <title>Installation</title> <para> @@ -30,7 +183,7 @@ <itemizedlist> <listitem> <simpara> - You need at least PHP 4.1.0 and libpx >= 0.0.9 + You need at least PHP 5.0.0 and libpx >= 0.1.9 </simpara> </listitem> <listitem> @@ -41,12 +194,98 @@ </itemizedlist> </para> </sect2> + <sect2 id="pecl.paradox.configuration"> <title>Configuration</title> <para> </para> </sect2> + + <sect2 id="pecl.paradox.oo-api"> + <title>Object oriented API</title> + <para> + The paradox extension provides also an + object oriented API. It consists of only one class called + paradox_doc. Its methods only differ from the functions + in its name and of course the missing first parameter. + The following table will list all methods and its + equivalent functions. + + <table id="pecl.paradox.table-class-methods"> + <title>Methods of class paradox_doc</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Name of method</entry> + <entry>Equivalent function</entry> + </row> + </thead> + <tbody> + <row> + <entry>Constructor</entry> + <entry><function>px_new</function></entry> + </row> + <row> + <entry>Destructor</entry> + <entry><function>px_delete</function></entry> + </row> + <row> + <entry><function>open_fp</function></entry> + <entry><function>px_open_fp</function></entry> + </row> + <row> + <entry><function>create_fp</function></entry> + <entry><function>px_create_fp</function></entry> + </row> + <row> + <entry><function>close</function></entry> + <entry><function>px_close</function></entry> + </row> + <row> + <entry><function>numrecords</function></entry> + <entry><function>px_numrecords</function></entry> + </row> + <row> + <entry><function>numfields</function></entry> + <entry><function>px_numfields</function></entry> + </row> + <row> + <entry><function>get_record</function></entry> + <entry><function>px_get_record</function></entry> + </row> + <row> + <entry><function>put_record</function></entry> + <entry><function>px_put_record</function></entry> + </row> + <row> + <entry><function>get_field</function></entry> + <entry><function>px_get_field</function></entry> + </row> + <row> + <entry><function>get_schema</function></entry> + <entry><function>px_get_schema</function></entry> + </row> + <row> + <entry><function>get_info</function></entry> + <entry><function>px_get_info</function></entry> + </row> + <row> + <entry><function>set_targetencoding</function></entry> + <entry><function>px_set_targetencoding</function></entry> + </row> + <row> + <entry><function>set_tablename</function></entry> + <entry><function>px_set_tablename</function></entry> + </row> + </tbody> + </tgroup> + </table> + + </para> + </sect2> + </sect1> + </partintro> <refentry id="pecl.paradox.px-new"> @@ -59,16 +298,65 @@ <funcsynopsis> <funcprototype> <funcdef>resource <function>px_new</function></funcdef> - <paramdef>void <parameter></parameter></paramdef> + <paramdef>void <parameter></parameter></paramdef> </funcprototype> </funcsynopsis> <para> Create a new paradox object. You will have to call this function - before any further functions. + before any further functions. <function>px_new</function> does not + create any file on the disk, it justs creates an instance of a paradox + object. Returns FALSE on failure. + </para> + <para> + <example> + <title>Opening a Paradox database</title> + <programlisting role="php"> +<![CDATA[ +<?php +if(!$pxdoc = px_new()) { + /* Error handling */ +} +$fp = fopen("test.db", "r"); +if(!px_open_fp($pxdoc, $fp)) { + /* Error handling */ +} +// ... +px_close($pxdoc); +px_delete($pxdoc); +fclose($fp); +?> +]]> + </programlisting> + </example> + </para> + <para> + If you prefer the object oriented API, then the above example will look + like the following. + <example> + <title>Opening a Paradox database</title> + <programlisting role="php"> +<![CDATA[ +<?php +$fp = fopen("test.db", "r"); +$pxdoc = new paradox_db(); +if(!$pxdoc->open_fp($fp)) { + /* Error handling */ +} +// ... +$pxdoc->close(); +fclose($fp); +?> +]]> + </programlisting> + </example> + </para> + <para> + See also <function>px_open_fp</function>, <function>px_delete</function>. </para> </refsect1> </refentry> - <refentry id="pecl.paradox.px-open-fp"> + + <refentry id="pecl.paradox.px-open-fp"> <refnamediv> <refname>px_open_fp</refname> <refpurpose>Open paradox database</refpurpose> @@ -84,12 +372,88 @@ </funcsynopsis> <para> Open an existing paradox database file. The actual file has to + be opened before with <function>fopen</function>. The first parameter + is the return value of <function>px_new</function>. This function can + also be used to open primary index files and tread them like a paradox + database. This is supported for those who would like to investigate + a primary index. It cannot be used to accelerate access to a database + file. Returns FALSE on failure. + </para> + <para> + See also example at <function>px_new</function>, <function>fopen</function>. + </para> + </refsect1> + </refentry> + + <refentry id="pecl.paradox.px-create-fp"> + <refnamediv> + <refname>px_create_fp</refname> + <refpurpose>Create a new paradox database</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>px_create_fp</function></funcdef> + <paramdef>resource <parameter>pxdoc</parameter></paramdef> + <paramdef>array <parameter>fielddesc</parameter></paramdef> + <paramdef>resource <parameter>file</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Create a new paradox database file. The actual file has to be opened before with fopen(). The first parameter is the return - value of px_new(). + value of px_new(). <option>fielddesc</option> is an array containing + one element for each field containing is specification. Each field + specification is an array itself with either two or three elements. + The first element is always a string values used as the name of field. + It may not be larger than ten characters. The second element contains + the field type which is one of the constants listed in table <link + linkend="pecl.paradox.table-fieldtypes">Constants for field types</link>. + In the case of a + character field, you will have to provide a third element specifying + the length of the field. + </para> + <note> + <para>This function is highly experimental, due to insufficient + documentation of the paradox file format. Database files created + with this function can be opened by <function>px_open_fp</function> + but probably cannot be opened by the Paradox software.</para> + </note> + <para> + <example> + <title>Creating a Paradox database with two fields</title> + <programlisting role="php"> +<![CDATA[ +<?php +if(!$pxdoc = px_new()) { + /* Error handling */ +} +$fp = fopen("test.db", "w+"); +$fields = array(array("col1", "S"), array("col2", "I")); +if(!@px_create_fp($pxdoc, $fields, $fp)) { + /* Error handling */ +} +px_set_tablename($pxdoc, "testtable"); +for($i=-50; $i<50; $i++) { + $rec = array($i, -$i); + px_put_record($pxdoc, $rec); +} +px_close($pxdoc); +px_delete($pxdoc); +fclose($fp); +?> +]]> + </programlisting> + </example> + </para> + <para> + See also <function>px_new</function>, <function>fopen</function>, + <function>px_put_record</function>. </para> </refsect1> - </refentry> + <refentry id="pecl.paradox.px-close"> <refnamediv> <refname>px_close</refname> @@ -104,10 +468,16 @@ </funcprototype> </funcsynopsis> <para> - Close the paradox database. + Close the paradox file. This function will not close the file. You will + have to call <function>fclose</function> afterwards. + </para> + <para> + See also <function>px_open_fp</function>, the example at + <function>px_new</function>. </para> </refsect1> </refentry> + <refentry id="pecl.paradox.px-delete"> <refnamediv> <refname>px_delete</refname> @@ -126,6 +496,7 @@ </para> </refsect1> </refentry> + <refentry id="pecl.paradox.px-get-record"> <refnamediv> <refname>px_get_record</refname> @@ -135,17 +506,55 @@ <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>bool <function>px_delete</function></funcdef> + <funcdef>array <function>px_get_record</function></funcdef> <paramdef>resource <parameter>pxdoc</parameter></paramdef> <paramdef>int <parameter>num</parameter></paramdef> <paramdef>int <parameter><optional>mode</optional></parameter></paramdef> </funcprototype> </funcsynopsis> <para> - Deletes the resource of the paradox file and frees all memory. + Returns the num'th record from the paradox database. The record is + returned as an associated array with its keys being the field names. + <parameter>mode</parameter> can be PX_KEYTOLOWER or PX_KEYTOUPPER + in order to convert the keys into lower or upper case. If + <parameter>mode</parameter> is not passed or is 0, then the key will be + exactly + like the field name. The element values will contain the field values. + NULL values will be retained and are different from 0.0, 0 or the empty + string. Currently only values for fields of type PX_FIELD_ALPHA, + PX_FIELD_SHORT, PX_FIELD_LONG, PX_FIELD_AUTOINC, PX_FIELD_NUMBER, + PX_FIELD_CURRENCY and PX_FIELD_LOGICAL are supported. Fields of + unsupported type will not be part of the array. This means, that + the return value of <function>px_num_fields</function> may differ + from the number of elements in the array returned by this function.</para> + <para> + The record number is an artificial number counting records in the + order as they are stored in the database. The first record has number 0. </para> </refsect1> </refentry> + + <refentry id="pecl.paradox.px-put-record"> + <refnamediv> + <refname>px_put_record</refname> + <refpurpose>Stores record into paradox database</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>px_put_record</function></funcdef> + <paramdef>resource <parameter>pxdoc</parameter></paramdef> + <paramdef>array <parameter>record</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Stores a record into a paradox database. The record is added at the + end of the database. + </para> + </refsect1> + </refentry> + <refentry id="pecl.paradox.px-numrecords"> <refnamediv> <refname>px_numrecords</refname> @@ -160,10 +569,13 @@ </funcprototype> </funcsynopsis> <para> - Returns the number of records in a database file. + Returns the number of records in a database file. The return value + of this function is identical to the element 'numrecords' in the + associated array returned by <function>px_get_info</function>. </para> </refsect1> </refentry> + <refentry id="pecl.paradox.px-numfields"> <refnamediv> <refname>px_numfields</refname> @@ -178,10 +590,13 @@ </funcprototype> </funcsynopsis> <para> - Returns the number of fields in a database file. + Returns the number of fields in a database file. The return value + of this function is identical to the element 'numfields' in the + associated array returned by <function>px_get_info</function>. </para> </refsect1> </refentry> + <refentry id="pecl.paradox.px-get-schema"> <refnamediv> <refname>px_get_schema</refname> @@ -197,14 +612,43 @@ </funcprototype> </funcsynopsis> <para> - Returns the schema of a database file. + Returns the schema of a database file as an associated array. The key + name is equal to the field name. If <parameter>mode</parameter> is + PX_KEYTOLOWER or PX_KEYTOUPPER the key will be converted to lower or + upper case. If <parameter>mode</parameter> is 0 or not passed at all, + then the key name will be identical to the field name. Each array + element is itself an associated array containing the two fields + 'type' and 'size'. 'type' is one of the constants in table <link + linkend="pecl.paradox.table-fieldtypes">Constants for field types</link>. </para> </refsect1> </refentry> + + <refentry id="pecl.paradox.px-get-field"> + <refnamediv> + <refname>px_get_field</refname> + <refpurpose>Returns the specification of a single field</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>px_get_field</function></funcdef> + <paramdef>resource <parameter>pxdoc</parameter></paramdef> + <paramdef>int <parameter><optional>fieldno</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns the specification of the fieldno'th database field as an associated + array. The array contains three fields named 'name', 'type' and 'size'. + </para> + </refsect1> + </refentry> + <refentry id="pecl.paradox.px-set-targetencoding"> <refnamediv> <refname>px_set_targetencoding</refname> - <refpurpose>Sets the encoding of the output</refpurpose> + <refpurpose>Sets the encoding for character fields</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -216,10 +660,139 @@ </funcprototype> </funcsynopsis> <para> - Set the encoding of the output. + Set the encoding data retrieved from character fields. All character + fields will be recoded + to the encoding set by this function. If the encoding is not set, the + character data will be returned in the DOS code page encoding as + specified in the database. Returns FALSE if encoding could not be set, + e.g. the encoding is unknown, or pxlib does not support recoding at all. + In the second case a warning will be issued. + </para> + <para> + See also <function>px_get_info</function> to determine the DOS code page. </para> </refsect1> </refentry> + + <refentry id="pecl.paradox.px-set-tablename"> + <refnamediv> + <refname>px_set_tablename</refname> + <refpurpose>Sets the name of a table</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>px_set_tablename</function></funcdef> + <paramdef>resource <parameter>pxdoc</parameter></paramdef> + <paramdef>string <parameter>name</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Sets the table name of a paradox database, which was created with + <function>px_create_fp</function>. Applying this function on an + existing database has no effect. + </para> + </refsect1> + </refentry> + + <refentry id="pecl.paradox.px-get-info"> + <refnamediv> + <refname>px_get_info</refname> + <refpurpose>Return lots of information about a paradox file</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>px_get_info</function></funcdef> + <paramdef>resource <parameter>pxdoc</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns an associated array with lots of information about a paradox + file. This array is likely to extend in the future. + </para> + <variablelist> + <varlistentry> + <term>fileversion</term> + <listitem> + <para>Version of file multiplied by 10. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>tablename</term> + <listitem> + <para>Name of table as stored in the the file. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>numrecords</term> + <listitem> + <para>Number of records in this database. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>numfields</term> + <listitem> + <para>Number of fields in the table. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>headersize</term> + <listitem> + <para>Number of bytes used for the header. This is usally 0x800. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>maxtablesize</term> + <listitem> + <para>This value multiplied by 0x400 is the size of a data block. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>numdatablocks</term> + <listitem> + <para>The number of data blocks in the file. Each data block contains + a certain number of records which depends on the record size and + the data block size (maxtablesize). Data blocks may not necessarily + be completely filled. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>numindexfields</term> + <listitem> + <para>Number of fields used for the primary index. The fields do + always start as field number 1. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>codepage</term> + <listitem> + <para>The DOS codepage which was used for encoding fields which + character data. If the target encoding is not set with + <function>px_set_targetencoding</function> this will be the encoding + for character fields when access records with + <function>px_get_record</function>. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + See also <function>px_numfields</function>, + <function>px_numrecords</function>. + </para> + </refsect1> + </refentry> + </reference> <!-- Keep this comment at the end of the file