             PDXPP -- The Paradox Class Libraries for C++
                       Functional Documentation


   Overview

   The PDXPP class library allows the programmer to access the
   Paradox Engine using C++ class objects.  This not only allows the
   programmer to maintain an object-oriented programming approach,
   but also hides many of the mundane tasks of using the Paradox
   Engine.

   The PDXPP class library was written by Gary B. Weinfurther.  It
   is released into the public domain.  No warranties, expressed or
   implied, are given with the library.  The author is not
   responsible for the results, or lack therof, obtained from the
   use or disuse of this library.

   There are five classes within the PDXPP library:

      PXOBJ     - Abstract base class for the other PDXPP classes.
      PXTABLE   - Table-based operations.
      PXFIELD   - Field-based operations.
      PXRECORD  - Operations with record transfer buffers.
      PXLOCK    - Record-locking operations.

   This documentation, as well as this library, assumes prior
   knowledge of C++ and of the Paradox Engine.  In fact, this
   library does not attempt to replace the entire functionality of
   the Paradox Engine; doing so would not be of any necessary
   benefit to the programmer.  Instead, the purpose of the PDXPP
   library is to allow the manipulation of tables, fields, and
   records through C++ objects.

   Not all of the functions within the Paradox Engine have
   corresponding functions in this library.  Primarily, those
   functions which manipulate the Paradox Engine environment or
   perform file-level operations are not duplicated, and should be
   called directly.  A list of these functions is given in Appendix
   1.

   Class PXOBJ

   This is the base class of all of the PDXPP classes.  It provides
   an error-checking mechanism and a table handle for all derived
   classes.  Member functions include:


   TABLEHANDLE TblHandle();

       Returns the table handle of the object.


   int Result();

       Returns the error code of the last operation on this object.
       This is a Paradox Engine error code.


   char *ErrMsg();

       Returns a pointer to a string containing an error message
       describing the result of the last operation on this object.


   Object Evaluation

   The ! operator and the (void *) operator have been overloaded so
   you can test an instance of the PXOBJ or a derived class for
   validity.  A non-zero result indicates that the last operation on
   the object was successful.  A zero result indicates that the last
   operation was not successful, and you should examine the result
   of Result() or ErrMsg() to determine the cause of the error.

   For example:

       PXTABLE mytable("mytable");
       if(!mytable)
           {
           cout << mytable.ErrMsg();
           exit(mytable.Result());
           }

   Class PXTABLE

   This class is used to represent a Paradox table.  An object of
   this class may be defined to open an existing table or to create
   a new table.  Destruction of a PXTABLE object causes the
   associated table to be closed.

   Constructors:

   PXTABLE(char *name, int index = 0, int saveEveryChange = FALSE);

       Use this constructor to open an existing table.  Refer to the
       PXTblOpen() function in the Paradox Engine for information on
       the index and saveEveryChange parameters.


   PXTABLE(char *name, int nFlds, char **fldnames, char **types, int
           saveEveryChange = FALSE);

       Use this constructor to create a new table.  Once created,
       the table will be opened.  Be sure to test for success.

   Methods:

   int Name(int bufSize, char *namestr);

       Retrieves the name of the table.  bufSize is the lenth of the
       buffer which namestr points to.


   RECORDNUMBER NRecs();

       Returns the number of records in the table.


   int NFlds();

       Returns the number of fields in the table.


   int KeyNFlds();

       Returns the number of key fields in the table.


   int RecLocked();

       Returns a non-zero value if the current record in the table
       is locked.


   int Changed();

       Tests whether the table has been changed.


   int Lock(int lockType);

       Places a lock of the specified type on the entire table.
       Returns the Paradox Engine error code (0 = success).


   int Unlock(int lockType);

       Removes a lock of the specified type from the table.  Returns
       the Paradox Engine error code.


   int Refresh()

       Re-synchronizes the table.  Returns the Paradox Engine error
       code.


   int RecDelete();

       Deletes the current record from the table.  The current
       record can be selected with either the PXTABLE class or the
       PXRECORD class, so use caution.  Returns the Paradox Engine
       result code.


   int First();

       Moves the current record pointer to the first record in the
       table.  The current record pointer can be moved with either
       the PXTABLE class or the PXRECORD clas, so use caution.
       Returns the Paradox Engine result code.


   int Last();

       Moves the current record pointer to the last record in the
       table.  The current record pointer can be moved with either
       the PXTABLE class or the PXRECORD class, so use caution.
       Returns the Paradox Engine result code.


   int Next();

       Moves the current record pointer to the next record in the
       table.  The current record pointer can be moved with either
       the PXTABLE class or the PXRECORD class, so use caution.
       Returns the Paradox Engine result code.


   int Prev();

       Moves the current record pointer to the previous record in
       the table.  The current record pointer can be moved with
       either the PXTABLE class or the PXRECORD class, so use
       caution.  Returns the Paradox Engine result code.


   RECORDNUMBER RecNum();

       Returns the current record number.  Because Paradox is a
       multi-user database, this number may not reflect the same
       data at different times, so use with caution.


   int Goto(RECORDNUMBER recnum);

       Moves the current record pointer to the specified record
       number.  Returns the Paradox Engine result code.


   Class PXFIELD

   This class is used to represent fields within a table.  Create an
   object of this type for each field you wish to access.

   Constructors:


   PXFIELD(PXTABLE &pxtable, char *fldname);

       Creates a PXFIELD object using a PXTABLE object.  Specify the
       PXTABLE object and the name of the field.


   PXFIELD(TABLEHANDLE th, char *fldname);

       Creates a PXFIELD object using a table handle.  Specify the
       table handle and the name of the field.


   FIELDHANDLE FldHandle();

       Returns the field handle of the object.


   int FldName(int bufSize, char *buffer);

       Retrieves the name of the field.  <bufSize> is the maximum
       length of the buffer to which <buffer> points.


   int FldBlank();

       Tests if the field value for the current record is blank.
       The current record pointer can be moved by an object of
       either the PXTABLE class or the PXRECORD class, so use
       caution.


   int FldType(int bufSize, char *type);

       Retrieves the field type of the object.  <bufSize> is the
       maximum size of the buffer to which <type> points.

   Class PXRECORD

   Objects of this class represent independent record transfer
   buffers.  At least one is required for most table operations.
   When performing field-level operations, a PXFIELD object or a
   FIELDHANDLE is required for each individual field to be acted
   upon.

   Constructors:

   PXRECORD(PXTABLE &pxtable);

       Creates a PXRECORD object for the specified table.


   PXRECORD(TABLEHANDLE th);

       Creates a PXRECORD object for the specified table handle.


   PXRECORD(PXRECORD &sourcerec);

       Creates a PXRECORD object from an existing PXRECORD object.
       The new object is tied to the same table as the original
       object, and the contents of the original record transfer
       buffer are copied to the new object.

   Methods:

   RECORDHANDLE RecordHandle();

       Returns the record handle.


   int NFlds(void);

       Returns the number of fields in the table.


   int Append();

       Appends the contents of the record transfer buffer to the end
       of the table.  Returns the Paradox Engine result code.


   int Update();

       Updates the current record with the contents of the record
       transfer buffer.  Returns the Paradox Engine result code.


   int RecGet();

       Places the contents of the current record into the record
       transfer buffer.  Returns the Paradox Engine result code.


   int Insert();

       Inserts a new record into the table using the contents of the
       record transfer buffer.  Returns the Paradox Engine result
       code.


   int Empty();

       Empties the contents of the record transfer buffer.  Returns
       the Paradox Engine result code.


   int Delete();

       Deletes the current record from the table.  The current
       record pointer can be moved by an object of either the
       PXTABLE class or the PXRECORD class, so use caution.


   RECORDNUMBER RecNum();

       Returns the current record number.


   int Goto(RECORDNUMBER recnum);

       Moves the current record pointer to the specified record
       number.  Returns the Paradox Engine result code.


   int First();

       Moves the current record pointer to the first record in the
       table.  The current record pointer can be moved with either
       the PXTABLE class or the PXRECORD class, so use caution.
       Returns the Paradox Engine result code.


   int Last();

       Moves the current record pointer to the last record in the
       table.  The current record pointer can be moved with either
       the PXTABLE class or the PXRECORD class, so use caution.
       Returns the Paradox Engine result code.


   int Next();

       Moves the current record pointer to the next record in the
       table.  The current record pointer can be moved with either
       the PXTABLE class or the PXRECORD class, so use caution.
       Returns the Paradox Engine result code.


   int Prev();

       Moves the current record pointer to the previous record in
       the table.  The current record pointer can be moved with
       either the PXTABLE class or the PXRECORD class, so use
       caution.  Returns the Paradox Engine result code.


   int SrchFld(PXFIELD &field, int scope = SEARCHFIRST);

       Searches the specified field using the contents of the record
       transfer buffer.  Optionally, you may specify a FIELDHANDLE
       instead of a PXFIELD object.  Returns the Paradox Engine
       result code.


   int SrchKey(int nFlds, int scope = SEARCHFIRST)

       Searches using the specified number of key fields and the
       contents of the record transfer buffer.  Returns the Paradox
       Engine result code.


   int Put(PXFIELD &field);

       Puts a blank into the specified field of the record transfer
       buffer.  You may optionally specify a FIELDHANDLE instead of
       a PXFIELD object.  Returns the Paradox Engine result code.


   int Put(PXFIELD &field, short s);

       Puts a short integer into the specified field of the record
       transfer buffer.  You may optionally specify a FIELDHANDLE
       instead of a PXFIELD object.  Returns the Paradox Engine
       result code.


   int Put(PXFIELD &field, long l);

       Puts either a long integer or a date into the specified field
       of the record transfer buffer.  You may optionally specify a
       FIELDHANDLE instead of a PXFIELD object.  Returns the Paradox
       Engine result code.

   int Put(PXFIELD &field, double d);

       Puts a double into the specified field of the record transfer
       buffer.  You may optionally specify a FIELDHANDLE instead of
       a PXFIELD object.  Returns the Paradox Engine result code.


   int Put(PXFIELD &fiekd, int m, int d, int y);

       Puts a date into the specified field of the record transfer
       buffer.  You may optionally specify a FIELDHANDLE instead of
       a PXFIELD object.  Returns the Paradox Engine result code.


   int Put(PXFIELD &field, char *a);

       Puts a string into the specified field of the record transfer
       buffer.  You may optionally specify a FIELDHANDLE instead of
       a PXFIELD object.  Returns the Paradox Engine result code.


   int Get(PXFIELD &field, short &s);
   int Get(PXFIELD &field, long &l);
   int Get(PXFIELD &field, double &d);
   int Get(PXFIELD &field, int bufSize, char *a);
   int Get(PXFIELD &field, int &m, int &d, int &y);

       Retreives the contents of the specified field from the record
       transfer buffer.  You may optionally specify a FIELDHANDLE
       instead of a PXFIELD object.  Specify a reference to a long
       integer for either a numeric field or a date field.  Returns
       the Paradox Engine result code.

   Operators:

   Operator =(PXRECORD &sourceRec);

       Use the assignment operator to copy the contents of one
       record transfer buffer to another.  The two record transfer
       buffers do not need to be tied to the same table, but the
       structure of the tables must be identical.

   Class PXLOCK

   Each object of this class represents a lock on a record in the
   specified table.  A PXLOCK can constructed using either a PXTABLE
   object or a PXRECORD object.  In either case the lock is placed
   on the current record in the table.  Be sure to test for success
   after creating a PXLOCK object.  A lock may be removed by the
   destruction of the object or by using the Unlock() method.

   Constructors:


   PXLOCK(PXTABLE &pxtable);

       Places a lock on the current record in the specified table.


   PXLOCK(PXRECORD &pxrecord);

       Places a lock on the current record in the table associated
       with the PXRECORD object.

   Methods:

   LOCKHANDLE LockHandle();

       Returns the lock handle of the object.


   int Unlock();

       Attempts to remove the lock.  Returns the Paradox Engine
       result code.


   int Goto();

       Moves the current record pointer to the locked record.
       Returns the Paradox Engine result code.

   Using PDXPP

   All you need is PDXPP.H.  Just include it in your source code and
   use it.  All functions and methods are inline.  It is not
   necessary to include PXENGTCL.H as well.


   Sample Program

   #include <iostreams.h>
   #include "pdxpp.h"

   void main()
   {
       if(PXInit() != PXSUCCESS)
           {
           cout << "Unable to initialize the engine!";
           exit(1);
           }

       PXTABLE payments("payments");
       if(!payments)
           {
           cout << "Unable to open table.";
           exit(1);
           }

       PXRECORD rtb(payments);

       PXFIELD fInvNum(payments, "Inv #");
       PXFIELD fAmount(payments, "amount");
       PXFIELD fCheckDate(payments, "Check Date");
       PXFIELD fCheckNum(payments, "Check #");

       short invNum;
       long checkNum;
       int m,d,y;
       double amount;

       for(rtb.First(); rtb; rtb.Next())
           {
           rtb.Get(fInvNum, invNum);
           rtb.Get(fAmount, amount);
           rtb.Get(fCheckDate, m, d, y);
           rtb.Get(fCheckNum, checkNum);

           cout << invNum << fCheckNum << m << d << y%100 << amount;
           cout << nl;
           }

       PXExit();
   }

   Appendix 1: Paradox Engine Functions not represented.

   PXExit
   PXGetDefaults
   PXInit
   PXKeyAdd
   PXKeyDrop
   PXNetErrUser
   PXNetInit
   PXNetUserName
   PXPswAdd
   PXPswDel
   PXSetDefaults
   PXSetHWHandler
   PXTblAdd
   PXTblCopy
   PXTblDecrypt
   PXTblDelete
   PXTblEmpty
   PXTblEncrypt
   PXTblExist
   PXTblMaxSize
   PXTblProtected
   PXTblRename

