;;kdbfcomp.txt
;;950710
;;
;;  KDBF compatibility notes
;;

KDBF compatability is retained in most areas, with the following key
exceptions:

  1) All TBCursor, TBDatabase, TBEngine, and TBRecord arguments are
      references, not pointers

  2) TBCursor::recGeneric is analogous to BCursor::genericRec, but is
      not accessible without using the TBCursor::Rec() or TBCursor::RecRO()
      functions.

  3) TBCursor, TBDatabase and TBRecord functions are all classified as
      "const" functions or not based on whether they affect the underlying
      DATABASE, not the underlying class.

  4) Exceptions (of type TTdbfExc) are thrown to the caller on most errors.

  5) TBRecord::copyTo() copies any BLOB fields' contents also, unless
      the first argument is false (defaults to true).

There are a number of KDBF "superset" functions in the TDBF:

  TBCursor::TBCursor(const TBCursor &copyCur)
      //Copy Constructor, clones cursor, copies any BLOBs' contents from Rec()

  TBCursor::operator =(const TBCursor &copyCur)
      //Assignment operator

  Retcode   
  TBCursor::closeIfOpen() const
      //Ensures cursor is closed, returning without error either way

  Retcode   
  TBCursor::getFirstRecord() const
      //gotoBegin(), getNextRecord()

  Retcode   
  TBCursor::getLastRecord( TBRecord& rec ) const
      //gotoEnd(), getPreviousRecord()

  string    
  TBCursor::getTableName()
      //Returns tablename (if cursor attached)

  Retcode
  TBCursor::gotoRecGet( RECORDNUMBER recNum ) const
      //gotoRec(), getRecord()

  Retcode
  TBCursor::searchIndexRec( PXSearchMode mode,
                            int fldCnt = 1,
                            bool doGetRecord = false ) const
      //Use TBCursor::Rec() as arglist, option to do getRecord() to it


  Retcode
  TBCursor::searchNonIndex( const char* psFldName,
                            const char* psFldvalExpr,
                            bool    bLikePattern = false,
                            bool    doSearch = false )
      //Search on a non-indexed field (using a query)

  Retcode
  TBDatabase::appendTable() 
      //Arglist variations include source and destination cursors

  TBDatabase::beginTransaction( eXILType tranType )
      //Form where transaction handle not required

  Retcode
  TBDatabase::createTableBorrow( const char* psTblName,
                                 const char* psBorrowFrom,
                                 const TBDatabase& ptDbFrom = NULL )
      //Creates empty table in specified database, borrowing struct from another

  Retcode
  TBDatabase::deleteTableIfExists( const char* tblName )
      //Deletes specified table if it exists, return without error either way


  string
  TBDatabase::getAliasName()
      //Return alias name database is attached to


  Retcode
  TBDatabase::queryNoAnswer(const char *qryString,
                            DBIQryLang qryLang)
      //Use for changetos, deletes, updates, doesn't try to attach cursor

  Retcode
  TBDatabase::sortTable( const char* psTblname,
                         TSortTable& rtSortTable )
      //sort table as specified--NOTE ARGLIST LIKELY TO CHANGE

  TBEngine::TBEngine()
      //Constructors also read some idapi.cfg params to data members

  Retcode
  TBEngine::registerAllCallBacks( void* fnAll )
      //Register all IDAPI callbacks to one supplied function

  Retcode
  TBEngine::setPrivateDirAndCheck( const char *Directory )
      //Sets private dir, throws error if dir doesn't exist

  TBRecord::TBRecord( const TBRecord &copyCur )
      //Copy constructor, copies any BLOBs' contents

  TBRecord::operator =( const TBRecord &copyCur )
      //Assignment operator

  Retcode
  TBRecord::copyToSimilar( TBRecord& ptRecDest ) const
      //Like copyTo(), but goes by field name, not field number

  Retcode
  TBRecord::getField( const char *fldName, string& buf ) const
      //getField() to a string object

  string
  TBRecord::getFieldName( FIELDNUMBER h ) const
      //Return fieldname in a string object

  double
  TBRecord::getFloat( const string& fldName ) const
      //Return float field value

  INT32
  TBRecord::getInt32( const string& fldName ) const
      //Return long field value

  string
  TBRecord::getString( const string& fldName ) const
      //Return string field value

  BTimeStamp
  TBRecord::getTimestamp( const string& fldName ) const
      //Return BTimeStamp field value

  Retcode
  TBRecord::putField( char *fldName, const string& buf )
      //PutField() with a string argument
      
And, several "composition" and utility classes which encapsulate queries, 
blob fields and thrown exceptions:

  TBlobRO
    Encapsulate the opening, reading and closing of a text or binary blob field 
    in read-only mode. Member functions support segmented reads, and a future 
    release will support buffered line-at-a-time reads.

  TBlobRW
    Encapsulate the opening, reading, writing and closing of a text or binary 
    blob field in read/write mode. Member functions support segmented reads and
    writes, and a future release will support buffered line-at-a-time reads and
    writes.

  TTdbfExc
    Exception class, used to encapsulate error information for all TDBF
    thrown exceptions, including:
      TDBF interface function name
      TDBF interface class name
      IDAPI error number (if avail.)
      Alias name (if avail.)
      Table name (if avail.)
      Field name (if avail.)
      Text error message
      Text auxiliary information

  TQueryAnswerRO
    Encapsulate a query returning a read-only cursor. 

    Supports streaming of query text into ::Text()
    
    Returned cursor may be cloned (as long as cloned cursor is not written to).

  TQueryAnswerRW
    Encapsulate a query returning a read/write cursor (this is not a 
    true IDAPI updateable cursor, which is IDAPI does not formally support
    yet. Instead, the member function ::Update() is used to write back
    any changes made to the returned cursor).

    Supports streaming of query text into ::Text()
    
    Returned cursor may be cloned, and either the returned cursor or the
    cloned one written to.

  TQueryNoAnswer
    Encapsulate a query returning no cursor (changeto, delete and 
    update queries).

    Supports streaming of query text into ::Text()

-end-
        
