<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

<!-- Process this file with docbook-to-man to generate an nroff manual
     page: `docbook-to-man manpage.sgml > manpage.1'.  You may view
     the manual page with: `docbook-to-man manpage.sgml | nroff -man |
     less'.  A typical entry in a Makefile or Makefile.am is:

manpage.1: manpage.sgml
	docbook-to-man $< > $@

    
	The docbook-to-man binary is found in the docbook-to-man package.
	Please remember that if you create the nroff version in one of the
	debian/rules file targets (such as build), you will need to include
	docbook-to-man in your Build-Depends control field.

  -->

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  <!ENTITY dhfirstname "<firstname>UWE</firstname>">
  <!ENTITY dhsurname   "<surname>STEINMANN</surname>">
  <!-- Please adjust the date whenever revising the manpage. -->
  <!ENTITY dhdate      "<date>March 27, 2006</date>">
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
       allowed: see man(7), man(1). -->
  <!ENTITY dhsection   "<manvolnum>3</manvolnum>">
  <!ENTITY dhemail     "<email>uwe@steinmann.cx</email>">
  <!ENTITY dhusername  "Uwe Steinmann">
  <!ENTITY dhucpackage "<refentrytitle>PXLIB</refentrytitle>">
  <!ENTITY funcname    "pxlib">

  <!ENTITY debian      "<productname>Debian</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
]>

<refentry>
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;
    </author>
    <copyright>
     <year>2005-2006</year>
     <holder>&dhusername;</holder> 
		</copyright>
		&dhdate;
  </refentryinfo>
  <refmeta>
    &dhucpackage;

    &dhsection;
  </refmeta>
  <refnamediv>
    <refname>&funcname;</refname>

    <refpurpose>Library to read and write Paradox databases</refpurpose>
  </refnamediv>
  <refsect1>
    <title>DESCRIPTION</title>

    <para>pxlib is a library to read and write Paradox databases. It is far
		  from being complete but should be very helpful for those working on
			unix and having the need to handle paradox databases, blob files,
			primary and secondary indexes.
			</para>
		<para>pxlib is a C-library with bindings for Python and PHP.
		  The later is part of PECL (http://pecl.php.net).
		  This documentation will only describe the functions of the C-library,
			though most of what is said here can be applied to the other language
			bindings.
			The PHP extension of pxlib is documented in PEAR. The extension is
			called Paradox.</para>
		<para>This library is the base for a gnumeric plugin which has been
		  officially added to gnumeric in version 1.4.0. pxlib is also used
			by hk_classes which itself is the database access utilized by
			knoda (http://www.knoda.org).</para>

  </refsect1>
  <refsect1>
    <title>GETTING STARTED</title>

    <para>Programs which want to use pxlib will have to include the
		  header file <literal>paradox.h</literal> and link against libpx.
			If the libgsf file access is to be used <literal>paradox-gsf.h</literal>
			has to be included instead of <literal>paradox.h</literal>. The gsf
			library cannot be used currently for writing because pxlib requires
			read access on the database as well, which is not supported by libgsf.
			In such a case you will have to create a temporary file first and
			copy it the gsf stream afterwards.
		</para>
		<para>
			Before reading or writing a
			database file the library should be initialized with
			<function>PX_boot(3)</function>. It will set the locale and selects
			the messages in your language as defined by the environment variable
			LC_ALL. The library should
			be finalized by <function>PX_shutdown(3)</function>.</para>
		<para>A Paradox database is
			represented by a pointer to <literal>pxdoc_t</literal>. Such an object
			can be created with <function>PX_new(3)</function> and destroyed
			with <function>PX_delete(3)</function>.  You can easily handle
			several documents at the same time, each represented by its own
			pointer to <literal>pxdoc_t</literal>.</para>
		<para><literal>pxdoc_t</literal> is a faily large structure with various
		  information about the paradox file. Most of the needed information is
			stored in a substructure called <literal>px_head</literal>.
			<literal>px_head</literal> is defined as the following:</para>
	  <programlisting>
typedef struct px_head pxhead_t;
struct px_head {
  char *px_tablename;
  int px_recordsize;
  char px_filetype;
  int px_fileversion;
  int px_numrecords;
  int px_theonumrecords;
  int px_numfields;
  int px_maxtablesize;
  int px_headersize;
  int px_fileblocks;
  int px_firstblock;
  int px_lastblock;
  int px_indexfieldnumber;
  int px_indexroot;
  int px_numindexlevels;
  int px_writeprotected;
  int px_doscodepage;
  int px_primarykeyfields;
  char px_modifiedflags1;
  char px_modifiedflags2;
  char px_sortorder;
  int px_autoinc;
  int px_fileupdatetime;
  char px_refintegrity;
  struct px_field *px_fields;
};
	  </programlisting>
		<para>The structure is defined in <literal>paradox.h</literal> and can be
			accessed directly,
		  thought it is not encouraged at all, because the structure will
			disappear in the future. Most header values can already be read with
			<function>PX_get_value(3)</function> or
			<function>PX_get_parameter(3)</function> and set by
			<function>PX_set_value(3)</function> respectively
			<function>PX_set_parameter(3)</function></para>
		<para>The following example will do the basic
			preparation without creating nor opening a document on the disk.</para>
	  <programlisting>
...
#include &lt;paradox.h&gt;

main(int argc, char *argv[]) {
	pxdoc_t *pxdoc;

	PX_boot();
	pxdoc = PX_new();
	PX_delete(pxdoc);
	PX_shutdown();
}
	  </programlisting>
		<para>In order to actually read a Paradox database from disk you will
		  have to call</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PX_open_file</function></funcdef>
		    <paramdef>pxdoc_t *<parameter>pxdoc</parameter></paramdef>
		    <paramdef>const char *<parameter>filename</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>or</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PX_open_fp</function></funcdef>
		    <paramdef>pxdoc_t *<parameter>pxdoc</parameter></paramdef>
		    <paramdef>FILE *<parameter>fp</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para><function>PX_open_file(3)</function> will open an existing file
		  with the given file name, while <function>PX_open_fp(3)</function>
			will use an already open file. Both require a pointer to
			<literal>pxdoc_t</literal>.</para>
		<para>Extending the previous example with one of the former two functions
		  to open a database is just another small step as illustrated in the
			next example.</para>
	  <programlisting>
...
#include &lt;paradox.h&gt;

main(int argc, char *argv[]) {
	pxdoc_t *pxdoc;

	PX_boot();
	pxdoc = PX_new();
	PX_open_file(pxdoc, "test.db");
	PX_close(pxdoc);
	PX_delete(pxdoc);
	PX_shutdown();
}
	  </programlisting>
		<para>The database has to be closed with <function>PX_close(3)</function>.
			<function>PX_close(3)</function> will only close the file if it
			was opened by <function>PX_open_file(3)</function>.
			<function>PX_close(3)</function>
			is crucial because it also flushes unwritten blocks to disk.
			</para>
		<para>There are more sophisticated functions to create the handle for the
		  Paradox database.
		  They are used when error handling and memory management
			shall be controlled by the calling application. Check the manual pages
			<function>PX_new2(3)</function> and <function>PX_new3(3)</function> for
			a detailed description or read the section about memory management
			and error handler below.</para>
		<para>If you rather like to create a new Paradox database the above example
		  must call</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PX_create_file</function></funcdef>
		    <paramdef>pxdoc_t *<parameter>pxdoc</parameter></paramdef>
		    <paramdef>pxfield_t *<parameter>fields</parameter></paramdef>
		    <paramdef>int <parameter>numfields</parameter></paramdef>
		    <paramdef>const char *<parameter>filename</parameter></paramdef>
		    <paramdef>int <parameter>type</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>instead of <function>PX_open_file(3)</function>. Creating a Paradox file
			requires three further parameters to specify the database layout and the
			file type, e.g. pxfFileTypNonIndexDB. The function can be used to create
			both databases and primary index files. Secondary index files are not
			supported before version &lt;= 0.6.0 due to several bugs in pxlib.
			Since the format of a secondary index file is identical to a database
			file there is actually no need for special support of secondary indexes.
			It is left to the application to create them itself.
			pxlib &gt;= 0.6.0 can open databases for reading and writing
			and provide four new functions for this purpose. They will be
			described in the section `Modifying a database'.</para>
		<para>
			Each field of the database is described by a structure:</para>
	  <programlisting>
typedef struct px_field pxfield_t;
struct px_field {
  char *px_fname;
  char px_ftype;
  int px_flen;
  int px_fdc;
};
	  </programlisting>
		<para>The memory for the field array must be allocated by the
		  calling application using pxlibs' memory management functions,
			but will be freed by pxlib. For a list of available file types see the
			man page of <function>PX_create_fp(3)</function>.</para>


  </refsect1>

  <refsect1>
    <title>READING RECORDS FROM A DATABASE</title>

		<para>Data in a Paradox database is organized in records containing fields.
		  This is much like in other formats, e.g. dBase or a relational database
			system. Fields can be of 17 different data types as listed below.
			Field values are stored in
			sequential order in a record. A complete record is read by one of the
			functions
		</para>
    <funcsynopsis>
      <funcprototype>
	      <funcdef>int <function>PX_get_record</function></funcdef>
	 		<paramdef>pxdoc_t *<parameter>pxdoc</parameter></paramdef>
	      <paramdef>int <parameter>recno</parameter></paramdef>
	      <paramdef>char *<parameter>data</parameter></paramdef>
	      <paramdef>int <parameter>deleted</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>or</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PX_get_record2</function></funcdef>
				<paramdef>pxdoc_t *<parameter>pxdoc</parameter></paramdef>
		    <paramdef>int <parameter>recno</parameter></paramdef>
		    <paramdef>char *<parameter>data</parameter></paramdef>
		    <paramdef>int <parameter>deleted</parameter></paramdef>
		    <paramdef>pxdatablockinfo_t *<parameter>pxdbinfo</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
    <para>The second function returns additional data about the internal
		  location
			of the record within the file, which is mostly valueable for debugging
			or creating a seconday index.
			Both functions need a record number starting at 0 for the first record
			and a memory area large enough for the record. The size of that area
			can be determined by the function <function>PX_get_value(3)</function>
			when `recordsize' is passed as the value name. The record will read into
			that piece of memory straight from the database file without
			modifications.</para>
		<para>Paradox files can be encrypted. pxlib will automatically decrypt
		  a file while reading without the need to supply a password. This is
			possible because of a very weak encryption algorithmn and the password
			being stored in the database file itself.</para>
		<para>
			Once the record data has been read it can be accessed with a number of
			different functions depending on the field type. The following
			list contains the field type and the function needed to retrieve
			the value. Nothing can prevent you from accessing the record data
			in a different way if you know what you are doing.</para>
    <para>
		<variablelist>
		  <varlistentry>
			 <term>pxfAlpha</term>
			 <listitem><para>
			   <funcsynopsis>
				   <funcprototype>
					   <funcdef>int <function>PX_get_data_alpha</function></funcdef>
						 <paramdef>pxdoc_t *<parameter>pxdoc</parameter></paramdef>
						 <paramdef>char *<parameter>data</parameter></paramdef>
						 <paramdef>int <parameter>len</parameter></paramdef>
						 <paramdef>char **<parameter>value</parameter></paramdef>
					 </funcprototype>
				 </funcsynopsis>
         </para>
         <para>The field value will be automatically converted from the
           encoding used in the database file to the encoding set by
           <function>PX_set_parameter(3)</function> with parameter name
           set to 'targetencoding`. The string will be null terminated.
         </para>
         <para>This function allocates memory for the field data which must
           be freed by the application. The chunk of memory can be different
					 from len when encoding involves conversion from a 1-byte to a
					 2-byte character representaion. This is also the reason why the
					 application cannot precisly allocate the memory for the data and
					 it must be left to pxlib. Read the section about `Memory
					 allocation' for more details.
			  </para></listitem>
			</varlistentry>
		  <varlistentry>
			 <term>pxfDate</term>
			 <listitem><para>
			   <funcsynopsis>
				   <funcprototype>
					   <funcdef>int <function>PX_get_data_long</function></funcdef>
						 <paramdef>pxdoc_t *<parameter>pxdoc</parameter></paramdef>
						 <paramdef>char *<parameter>data</parameter></paramdef>
						 <paramdef>int <parameter>len</parameter></paramdef>
						 <paramdef>long *<parameter>value</parameter></paramdef>
					 </funcprototype>
				 </funcsynopsis>
			 </para>
			 <para>Fields of type date are actually 4 byte integer values counting
			   days since jan-00-0000. In order to convert it into 3 single integers
				 for year, month and
				 day, you will have to add 1721425 to the value and call the function
			 </para>
			 <para>
			   <funcsynopsis>
				   <funcprototype>
					   <funcdef>void <function>PX_SdnToGregorian</function></funcdef>
						 <paramdef>long int *<parameter>value</parameter></paramdef>
						 <paramdef>int *<parameter>year</parameter></paramdef>
						 <paramdef>int *<parameter>month</parameter></paramdef>
						 <paramdef>int *<parameter>day</parameter></paramdef>
					 </funcprototype>
				 </funcsynopsis>
			 </para>
			 <para>
			   in order to get a valid date. The value 1721425 is the number of days
				 between the start of the julian calendar (4714 BC) and jan-00-0000.
				 <parameter>len</parameter> must be set to 4.
			 </para>
			 </listitem>
			</varlistentry>
		  <varlistentry>
			 <term>pxfShort</term>
			 <listitem><para>
			   <funcsynopsis>
				   <funcprototype>
					   <funcdef>int <function>PX_get_data_short</function></funcdef>
						 <paramdef>pxdoc_t *<parameter>pxdoc</parameter></paramdef>
						 <paramdef>char *<parameter>data</parameter></paramdef>
						 <paramdef>int <parameter>len</parameter></paramdef>
						 <paramdef>short int *<parameter>value</parameter></paramdef>
					 </funcprototype>
				 </funcsynopsis>
			 </para>
			 <para>
			 	 This type is a short integer which is 2 bytes long.
				 <parameter>len</parameter> must be set to 2.
			 </para>
			 </listitem>
			</varlistentry>
		  <varlistentry>
			 <term>pxfLong, pxfAutoInc</term>
			 <listitem><para>
			   <funcsynopsis>
				   <funcprototype>
					   <funcdef>int <function>PX_get_data_long</function></funcdef>
						 <paramdef>pxdoc_t *<parameter>pxdoc</parameter></paramdef>
						 <paramdef>char *<parameter>data</parameter></paramdef>
						 <paramdef>int <parameter>len</parameter></paramdef>
						 <paramdef>long *<parameter>value</parameter></paramdef>
					 </funcprototype>
				 </funcsynopsis>
			 </para>
			 <para>
			 	 This type is a integer which is 4 bytes long.
				 <parameter>len</parameter> must be set to 4.
			 </para>
			 </listitem>
			</varlistentry>
		  <varlistentry>
			 <term>pxfNumber, pxfCurrency</term>
			 <listitem><para>
			   <funcsynopsis>
				   <funcprototype>
					   <funcdef>int <function>PX_get_data_double</function></funcdef>
						 <paramdef>pxdoc_t *<parameter>pxdoc</parameter></paramdef>
						 <paramdef>char *<parameter>data</parameter></paramdef>
						 <paramdef>int <parameter>len</parameter></paramdef>
						 <paramdef>double *<parameter>value</parameter></paramdef>
					 </funcprototype>
				 </funcsynopsis>
			 </para>
			 <para>
			 	 These types are floating poing numbers.
				 <parameter>len</parameter> must be set to 8.
			 </para></listitem>
			</varlistentry>
		  <varlistentry>
			 <term>pxfLogical</term>
			 <listitem><para>
				 <funcsynopsis>
					 <funcprototype>
						 <funcdef>int <function>PX_get_data_byte</function></funcdef>
						 <paramdef>pxdoc_t *<parameter>pxdoc</parameter></paramdef>
						 <paramdef>char *<parameter>data</parameter></paramdef>
						 <paramdef>int <parameter>len</parameter></paramdef>
						 <paramdef>char *<parameter>value</parameter></paramdef>
					 </funcprototype>
				 </funcsynopsis>
       </para>
			 <para>The extracted value is either 0 (false) or &lt;0 (true).
				 <parameter>len</parameter> must be set to 1.
			 </para></listitem>
			</varlistentry>
		  <varlistentry>
			 <term>pxfBLOb, pxfMemoBLOb, pxfFmtMemoBLOb</term>
			 <listitem><para>
				 <funcsynopsis>
					 <funcprototype>
						 <funcdef>int <function>PX_get_data_blob</function></funcdef>
						 <paramdef>pxdoc_t *<parameter>pxdoc</parameter></paramdef>
						 <paramdef>char *<parameter>data</parameter></paramdef>
						 <paramdef>int <parameter>len</parameter></paramdef>
						 <paramdef>int *<parameter>modnr</parameter></paramdef>
						 <paramdef>int *<parameter>blobsize</parameter></paramdef>
						 <paramdef>char **<parameter>value</parameter></paramdef>
					 </funcprototype>
				 </funcsynopsis>
       </para>
			 <para>
			   This function may not in any case succed. You should call
				 <function>PX_set_blob_file(3)</function> before to make sure even
				 blobs in a separate blob file can be retrieved. See the section
				 about reading blobs for more information.
			 </para></listitem>
			</varlistentry>
		  <varlistentry>
			 <term>pxfOLE</term>
			 <listitem><para>This type is not supported because there is too little
			   known about it. Accessing fields of type pxfOLE like fields
				 of type pxfBLOb may work.</para></listitem>
			</varlistentry>
		  <varlistentry>
			 <term>pxfGraphic</term>
			 <listitem><para>
				 <funcsynopsis>
					 <funcprototype>
						 <funcdef>int <function>PX_get_data_graphic</function></funcdef>
						 <paramdef>pxdoc_t *<parameter>pxdoc</parameter></paramdef>
						 <paramdef>char *<parameter>data</parameter></paramdef>
						 <paramdef>int <parameter>len</parameter></paramdef>
						 <paramdef>int *<parameter>modnr</parameter></paramdef>
						 <paramdef>int *<parameter>blobsize</parameter></paramdef>
						 <paramdef>char **<parameter>value</parameter></paramdef>
					 </funcprototype>
				 </funcsynopsis>
       </para>
			 <para>
			  This function has not been tested very well. 
       </para></listitem>
			</varlistentry>
		  <varlistentry>
			 <term>pxfTime</term>
			 <listitem><para>Use <function>PX_get_data_long(3)</function> as documented
			   at field type pxfDate. The value is the number of milli seconds since
				 midnight.</para></listitem>
			</varlistentry>
		  <varlistentry>
			 <term>pxfTimestamp</term>
			 <listitem><para>Use <function>PX_get_data_double(3)</function> and convert
			   the timestamp into a string with</para>
			 <para>
			   <funcsynopsis>
				   <funcprototype>
					   <funcdef>char *<function>PX_timestamp2string</function></funcdef>
						 <paramdef>pxdoc_t *<parameter>pxdoc</parameter></paramdef>
						 <paramdef>double *<parameter>value</parameter></paramdef>
						 <paramdef>const char *<parameter>format</parameter></paramdef>
					 </funcprototype>
				 </funcsynopsis>
			 </para>
			 <para><function>PX_timestamp2string(3)</function> takes a format string
			   as described in the manual page of the function and returns a string.
				 Alternatively you can process the value itself. It represents the
				 number of seconds since jan-00-0000. Dividing it by 86400 and
				 converting
				 it to an integer produces a value as stored in fields of type pxfTime.
			 </para>
			 </listitem>
			</varlistentry>
		  <varlistentry>
			 <term>pxfBCD</term>
			 <listitem><para>
			   <funcsynopsis>
				   <funcprototype>
					   <funcdef>int <function>PX_get_data_bcd</function></funcdef>
						 <paramdef>pxdoc_t *<parameter>pxdoc</parameter></paramdef>
						 <paramdef>char *<parameter>data</parameter></paramdef>
						 <paramdef>int <parameter>len</parameter></paramdef>
						 <paramdef>char **<parameter>value</parameter></paramdef>
					 </funcprototype>
				 </funcsynopsis>
         </para>
         <para>This function allocates memory for the field data which must
           be freed by the application.
         </para></listitem>
			</varlistentry>
		  <varlistentry>
			 <term>pxfBytes</term>
			 <listitem><para>
			   <funcsynopsis>
				   <funcprototype>
					   <funcdef>int <function>PX_get_data_bytes</function></funcdef>
						 <paramdef>pxdoc_t *<parameter>pxdoc</parameter></paramdef>
						 <paramdef>char *<parameter>data</parameter></paramdef>
						 <paramdef>int <parameter>len</parameter></paramdef>
						 <paramdef>char **<parameter>value</parameter></paramdef>
					 </funcprototype>
				 </funcsynopsis>
         <para>This function behaves like
           <function>PX_get_data_alpha(3)</function> except for the character
           conversion which does not take place. It will always copy
           exactely <parameter>len</parameter> bytes. This function
					 allocates memory for the field data which must be freed by
					 the application.
         </para></listitem>
			</varlistentry>
		</variablelist>
	  </para>
		<para>Each function takes the current Paradox database object as the first
			argument.  The second argument is the start of the field data. For the
			first field this will be the beginning of the whole record. The second
			field starts at an offset of length(first field), the third field starts
			at length(first field) plus length(second field) and so on. The
			<parameter>len</parameter> is the size of the field. The last parameter
			is a pointer to the data converted to an equivalent C type. Each function either
      returns 0 on success or a value &lt; 0 in case of an error. Nobody prevents
      you from
			accessing the data with the wrong function, or pointing towards the wrong
			position in the record. Check the manual page of each function for a more
      detailed description.</para>
    <para>Sequencialy reading records and fields from a
			Paradox database is illustrated in the next simplified example.</para>
	  <programlisting>
for(j=0; j&lt;pxh-&gt;px_numrecords; j++) {
  int offset;
  if(PX_get_record(pxdoc, j, data)) {
    offset = 0;
    pxf = pxh-&gt;px_fields;
    for(i=0; i&lt;pxh-&gt;px_numfields; i++) {
      switch(pxf-&gt;px_ftype) {
        case pxfAlpha: {
          char *value;
          if(0 &lt; PX_get_data_alpha(pxdoc, &amp;data[offset], pxf-&gt;px_flen, &amp;value)) {
            // ...
            pxdoc-&gt;free(pxdoc, value);
          } else {
            // ...
          }
          break;
        }
        case pxfDate: {
          long value;
          int year, month, day;
          if(0 &lt; PX_get_data_long(pxdoc, &amp;data[offset], pxf-&gt;px_flen, &amp;value)) {
            PX_SdnToGregorian(value+1721425, &amp;year, &amp;month, &amp;day);
            // ...
          } else {
            // ...
          }
          break;
        }
        case pxfShort: {
          short int value;
          if(0 &lt; PX_get_data_short(pxdoc, &amp;data[offset], pxf-&gt;px_flen, &amp;value)) {
            // ...
          } else {
            // ...
          }
          break;
        }
        case pxfAutoInc:
        case pxfLong: {
          long value;
          if(0 &lt; PX_get_data_long(pxdoc, &amp;data[offset], pxf-&gt;px_flen, &amp;value)) {
            // ...
          } else {
            // ...
          }
          break;
        }
        case pxfTimestamp: {
          double value;
          if(0 &lt; PX_get_data_double(pxdoc, &amp;data[offset], pxf-&gt;px_flen, &amp;value)) {
            char *str = PX_timestamp2string(pxdoc, value, "Y-m-d H:i:s");
            // ...
            pxdoc-&gt;free(pxdoc, str);
          } else {
            // ...
          }
          break;
        }
        case pxfTime: {
          long value;
          if(0 &lt; PX_get_data_long(pxdoc, &amp;data[offset], pxf-&gt;px_flen, &amp;value)) {
            // ...
          } else {
            // ...
          }
          break;
        }
        case pxfCurrency:
        case pxfNumber: {
          double value;
          if(0 &lt; PX_get_data_double(pxdoc, &amp;data[offset], pxf-&gt;px_flen, &amp;value)) {
            // ...
          } else {
            // ...
          }
          break;
        }
        case pxfLogical: {
          char value;
          if(0 &lt; PX_get_data_byte(pxdoc, &amp;data[offset], pxf-&gt;px_flen, &amp;value)) {
            if(value)
              // ...
            else
              // ...
          } else {
            // ...
          }
          break;
        }
        case pxfBLOb:
        case pxfGraphic:
        case pxfOLE:
        case pxfMemoBLOb:
        case pxfFmtMemoBLOb: {
            char *blobdata;
            int mod_nr, size, ret;
            if(pxf-&gt;px_ftype == pxfGraphic)
              ret = PX_get_data_graphic(pxdoc, &amp;data[offset], pxf-&gt;px_flen, &amp;mod_nr, &amp;size, &amp;blobdata);
            else
              ret = PX_get_data_blob(pxdoc, &amp;data[offset], pxf-&gt;px_flen, &amp;mod_nr, &amp;size, &amp;blobdata);
            if(ret &gt; 0) {
              if(blobdata) {
                // ...
                pxdoc-&gt;free(pxdoc, blobdata);
              } else {
                // ...
              }
            }
            break;
        }
        case pxfBCD: {
          char *value;
          int ret;
          if(0 &lt; (ret = PX_get_data_bcd(pxdoc, &amp;data[offset], pxf-&gt;px_fdc, &amp;value))) {
            // ..
            pxdoc-&gt;free(pxdoc, value);
          } else if(ret == 0) {
            // ..
          } else {
            // ..
          }
          break;
        }
        case pxfBytes:
          // ..
          break;
        default:
          break;
      }
    }
    offset += pxf-&gt;px_flen;
    pxf++;
  } else {
    fprintf(stderr, _("Couldn't get record number %d\n"), j);
  }
}
	  </programlisting>
  </refsect1>

  <refsect1>
    <title>WRITING RECORDS INTO A DATABASE</title>

		<para>Write support has been introduced into pxlib in version 0.1.9 but
		  should be still considered experimental, though there has been reports
			from users who has successfully used it.</para>
		<para>Writing paradox databases is
			quite similar to reading them, if you substitute
			<function>PX_open_file(3)</function> by
			<function>PX_create_file(3)</function> and
			<function>PX_get_record(3)</function> by
			<function>PX_put_record(3)</function>.</para>
		<para>Modifying the above example in order to create a simple database
		  with two columns will result in the following code:
		</para>
	  <programlisting>
...
#include &lt;paradox.h&gt;

main(int argc, char *argv[]) {
	pxdoc_t *pxdoc;
	pxfield_t pxf[2];
	int numfields = 2;

	PX_boot();
	pxdoc = PX_new();
	pxf[0].px_fname = PX_strdup(pxdoc, "column1");
	pxf[0].px_ftype = pxfShort;
	pxf[0].px_flen = 2;
	pxf[0].px_fdc = 0;
	pxf[1].px_fname = PX_strdup(pxdoc, "column2");
	pxf[1].px_ftype = pxfAlpha;
	pxf[1].px_flen = 20;
	pxf[1].px_fdc = 0;
	PX_create_file(pxdoc, pxf, numfields, "test.db", pxfFileTypNonIndexDB);
	PX_close(pxdoc);
	PX_delete(pxdoc);
	PX_shutdown();
}
	  </programlisting>
  </refsect1>

  <refsect1>
    <title>MODIFYING A DATABASE</title>

		<para>Starting from version 0.6.0 pxlib supports to open databases for
		  reading and writing at the same time. If you intend to do so, please
			ensure to open the file for the database in `w+', `r+', or `a+'
			mode. You will also have to use a new set of functions as described
			below.</para>

    <funcsynopsis>
	    <funcprototype>
		    <funcdef>int <function>PX_insert_record</function></funcdef>
			  <paramdef>pxdoc_t *<parameter>pxdoc</parameter></paramdef>
			  <paramdef>pxval_t **<parameter>data</parameter></paramdef>
		  </funcprototype>
	  </funcsynopsis>
		<para><function>PX_insert_record(3)</function> inserts a new record into
		  a database.</para>

    <funcsynopsis>
	    <funcprototype>
		    <funcdef>int <function>PX_update_record</function></funcdef>
			  <paramdef>pxdoc_t *<parameter>pxdoc</parameter></paramdef>
			  <paramdef>pxval_t **<parameter>data</parameter></paramdef>
			  <paramdef>int <parameter>recno</parameter></paramdef>
		  </funcprototype>
	  </funcsynopsis>
		<para><function>PX_update_record(3)</function> updates an existing
		  record in database.</para>

    <funcsynopsis>
	    <funcprototype>
		    <funcdef>int <function>PX_delete_record</function></funcdef>
			  <paramdef>pxdoc_t *<parameter>pxdoc</parameter></paramdef>
			  <paramdef>int <parameter>recno</parameter></paramdef>
		  </funcprototype>
	  </funcsynopsis>

    <funcsynopsis>
	    <funcprototype>
		    <funcdef>int <function>PX_retrieve_record</function></funcdef>
			  <paramdef>pxdoc_t *<parameter>pxdoc</parameter></paramdef>
			  <paramdef>int <parameter>recno</parameter></paramdef>
		  </funcprototype>
	  </funcsynopsis>

  </refsect1>

  <refsect1>
    <title>ENCODING</title>

		<para>Exchanging text is not problem as long as both parties use the same
		  encoding or stipulate to use plain 7 bit ascii. Paradox allows one to use
			any encoding with a know dos code page and saves the corresponding
			code page number in the
			header of the database. You can request this number with
			<function>PX_get_value(3)</function> by passing `codepage' as the value
			name. Reading fields of type <literal>pxfAlpha</literal> will return
			the unmodified value unless the target encoding has been set by
			<function>PX_set_parameter(3)</function> differently
			from the one stored in the database header. If the target encoding
			is set differently <function>PX_get_data_alpha(3)</function> will
			automatically convert into the requested encoding. This is either
			done be the iconv or recode library, depending on which one was
			found when pxlib was configured. If both were available iconv
			is preferred.</para>
  </refsect1>

  <refsect1>
    <title>READING BLOBS</title>

		<para>Paradox knows five field types which all represent a type of blob data.
		  Blobs can be stored in the database file but are usually stored in an extra
			file with the extension <literal>.MB</literal>. pxlib provides two functions
			to read blob data.</para>
		<para>
		  <funcsynopsis>
			  <funcprototype>
				  <funcdef>int <function>PX_get_data_blob</function></funcdef>
				  <paramdef>pxdoc_t *<parameter>pxdoc</parameter></paramdef>
				  <paramdef>char *<parameter>data</parameter></paramdef>
				  <paramdef>int <parameter>len</parameter></paramdef>
				  <paramdef>int *<parameter>modnr</parameter></paramdef>
				  <paramdef>int *<parameter>blobsize</parameter></paramdef>
				  <paramdef>char **<parameter>value</parameter></paramdef>
			  </funcprototype>
		  </funcsynopsis>
    </para>
		<para>and</para>
		<para>
		 <funcsynopsis>
			 <funcprototype>
				 <funcdef>int <function>PX_get_data_graphic</function></funcdef>
				 <paramdef>pxdoc_t *<parameter>pxdoc</parameter></paramdef>
				 <paramdef>char *<parameter>data</parameter></paramdef>
				 <paramdef>int <parameter>len</parameter></paramdef>
				 <paramdef>int *<parameter>modnr</parameter></paramdef>
				 <paramdef>int *<parameter>blobsize</parameter></paramdef>
				 <paramdef>char **<parameter>value</parameter></paramdef>
			 </funcprototype>
		 </funcsynopsis>
		</para>
		<para>The second function must be used for fields of type
		  <literal>pxfGraphic</literal>, the first function can be safely
			use for fields of type <literal>pxfBLOb</literal>,
			<literal>pxfMemoBLOb</literal>, and <literal>pxfFmtMemoBLOb</literal>.
		</para>
    <para>In order to read blob data from a .MB file one must first associate
		  that file with the database file by calling</para>
		<para>
		  <funcsynopsis>
			  <funcprototype>
				  <funcdef>int <function>PX_set_blob_file</function></funcdef>
				  <paramdef>pxdoc_t *<parameter>pxdoc</parameter></paramdef>
				  <paramdef>const char *<parameter>filename</parameter></paramdef>
			  </funcprototype>
		  </funcsynopsis>
		</para>
  </refsect1>

  <refsect1>
    <title>WRITING BLOBS</title>

		<para>Writing blobs is still the most experimental part of pxlib. There
		  has been already success stories but there are also some missing parts
			in the paradox file format which decreases confidence on those files.</para>
  </refsect1>

  <refsect1>
    <title>MEMORY MANAGEMENT, ERROR HANDLING</title>

    <para>pxlib uses by default its on memory management and error handling
		  functions. In many cases the calling application has its own memory
			management and error handling. pxlib can be told to use those
			functions by calling <function>PX_new3(3)</function> instead of
			<function>PX_new(3)</function>.</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PX_new3</function></funcdef>
		    <paramdef>pxdoc_t *<parameter>psdoc</parameter></paramdef>
		    <paramdef>(errorhandler *) <parameter>(pxdoc_t *p, int type, const char *msg, void *data)</parameter></paramdef>
		    <paramdef>(allocproc *) <parameter>(pxdoc_t *p, size_t size, const char *caller)</parameter></paramdef>
		    <paramdef>(reallocproc *) <parameter>(pxdoc_t *p, void *mem, size_t size, const char *caller)</parameter></paramdef>
		    <paramdef>(freeproc *) <parameter>(pxdoc_t *p, void *mem)</parameter></paramdef>
		    <paramdef>void *<parameter>errorhandler_user_data</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>The errorhandler and the last parameter
			<parameter>errorhandler_user_data</parameter> allows one to pass arbitrary
			data as the last parameter to its own errorhandler. This is quite often
			used if errors are being output in a widget of a graphical toolkit. The
			pointer to that widget can be passed as
			<parameter>errorhandler_user_data</parameter> and pxlib will pass it
			forward to the error handler.</para>

  </refsect1>
  <refsect1>
    <title>ENCRYPTION</title>

    <para>Paradox supports a very weak encryption of the data blocks. The
		  headers are not encrypted. Encryption is accomplished by three
			static tables with 256 bytes each and a long integer generated
			from a password. The integer is called the checksum of the password.
			The checksum is stored in the header of the .db file which makes
			it feasible to decrypt a file even without knowing the password.
			pxlib reads encrypted files silently without asking for additional
			information. Writing an encrypted file requires to supply a password
			for calculating the checksum. The password can be set with
			<function>PX_set_parameter(3)</function>. Once it is set, encryption
			is automatically turned on. The password must be set before writing
			any records. The best place to do this, is right after calling
			<function>PX_create_file(3)</function> or
			<function>PX_create_fp(3)</function>.</para>

  </refsect1>
  <refsect1>
    <title>SEE ALSO</title>

    <para>The detailed manual pages for each function of the library.</para>

  </refsect1>
  <refsect1>
    <title>AUTHOR</title>

    <para>This manual page was written by &dhusername; &dhemail;.</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:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->