;;readme.txt
;;950706
;;
;; readme for tdbf and TQuery classlibs
;;
;;  TDBF, a class derived from KDBF, written by:
;;    Buc Rogers (buc@mcs.com),
;;
;;  And with TQuery* classes, etc. written by:
;;    x Chris Smith (ccas@mcs.com)
;;    x Jacques Doornebos
;;

See also:
  example.cpp   Simple example code for engine init, query, blob usage
  grep.txt      detailed list of TDBF function prototypes and descriptions
  kdbfcomp.txt  KDBF compatibility notes

TDBF Release Notes:
  950710
    x TBCursor::close (and TBCursor::~TBCursor) now ensure any open blobs asso.
        w record are closed.
    x Repaired TBCursor copy-constructor and assignment operator to not
        GPF when copied cursor is not open
  950705
    x Added example code to example.cpp for RTL maxhandles check, TBlobRO,
        TBlobRW
    x New classes for large and/or binary BLOBs: TBlobRO, TBlobRW
    x TBRecord::copyTo() now has 2d argument (defaulted to true) which copies
        any BLOB fields' contents in source record to destination record
        (this is used in TBCursor copy constructor).

        Note that the blobs in the target record are left open in read/write
        mode (so next appendRec(), insertRec() or updateRec() writes them out).

    x TBRecord::copyToSimilar() now uses TBlobRO and TBlobRW to copy
        text or binary blobs of any size
  950628
    x Added TBCursor::closeIfOpen() function, does not throw exception
        if cursor already closed
    x Added TBDatabase::beginTransaction( eXILType tranType ) form
        (tranhandle no longer has to be supplied)
    x Modified TQueryAnswerRO::Run() and TQueryAnswerRW::Run() so they
        automatically close their cursors when Run() called more than
        once
    x TBoolean now obsolete (replaced with bool)
  950626
    x Renamed TBCursor::RecRd() to TBCursor::RecRO()
    x Renamed TQueryAnswer class to TQueryAnswerRO. Note that the Csr() and
        Rec() functions now return const references.
    x Added new TQueryAnswerRW class which supports writable
        returned cursor (note this writable cursor does NOT automatically
        update the queried table)
    x Added TBRecord copy constructor and assignment operator
  950619
    x appendTable( const TBCursor& csrSource, ... ) now returns with
        csrSource at BOF (previously, csrSource returned at EOF)
    x TQueryAnswer::Csr()--first call after Run() now guaranteed to be BOF
        even when SetResultTbl() was called
    x Added THeapPtrArray class, same as THeapPtr but for arrays of objects
        o Still doesn't support *[] operator
    x Updated TBCursor:: copy constructor and assignment operators to carry
        recGeneric through (and its contents)
    x Put TBRecord::TBRecord() default constructor back in
    x Added "TBCursor::RecRd() const" function, a const version of what
        "TBCursor::Rec()" does
    x tdbf.hpp include file now includes necessary Borland classlib to support
        "bool" type (TBoolean will be obs in a future release)
  950615
    x Changed all TBCursor:: functions which previously threw exceptions
        except for a group of 6 error codes to throw on ANY error (EXCEPT
        for EOF and BOF errors on getNextRecord() and getPreviousRecord()
        respectively).
    x Added functions:
        getFirstRecord()
        getLastRecord()
        gotoRecGet()
  950613
    x Added TBLob class, which manages reading and writing from BLOB fields
    x TBEngine constructor disables debug layer (which was enabled by BEngine
        constructor)
    x Added TBEngine::setDebugLayerOptions() function (which should be used
        to re-enable debug layer from the application, if desired)
  950612
    x TQueryAnswer::Rec() and TQueryNoAnswer::Rec() now return Csr().Rec(),
        which means ::Csr().getNextRecord() and other "generic rec" routines
        can be used with TQueryAnswer::Rec()
  950609
    x Added TBCursor::rec "generic record":
        x opened by constructor, attach() or open()
        x closed by destructor or close()
        x Existing functions added 
        x New form of searchIndex() which takes Rec() as argument
            (and optionally does getRecord() to Rec() on a find)
        x New form of searchIndex() having optional last param
            specifying whether to do a getRecord() on a find
    x Changed all TBCursor, TBDatabase, TBRecord functions which
        had TBCursor*, TBDatabase* or TBRecord* args to reference
    x Changed TBCursor::searchIndex() to take ref rather than  ptr
    x Changed TBRecord::copyToSimilar() to take reference rather than ptr
    x Changed TQueryAnswer, TQueryNoAnswer constructors to take only
        the database (engine arg not required or allowed)  
    x Changed TBDatabase::appendTable() TBCursor args to be references
        rather than pointers
    x Changed TBDatabase::appendTable() destType and dbDest args to
        be not defaulted (so dbDest could be a non-const), added
        appendTable() form where dbDest is not specified.
    x Changed TBDatabase::createTableBorrow() ptDbFrom arg to reference
    x Added TBRecord functions to return fields in return value:
        double          getFloat( const string& fldName ) const;
        INT32           getInt32( const string& fldName ) const;
        string          getString( const string& fldName ) const;
        BTimeStamp      getTimestamp( const string& fldName ) const;
  950608
    x Example file expanded to included deinitialization
    x DELETE_SAFE(), DELETE_A_SAFE() macros simplified
  950607
    x New example.cpp file
    x TQueryAnswer and TQueryNoAnswer classes replace TQuery
    x const functions added to both tdbf and kdbr (see grep.txt or
        tdbf.hpp for explanation of const function strategy)
  950525
    x Changed query() to not throw on query error (throws only on
        unexp. no cursor error)
  950524
    x Added string arg alternatives to getBlob(), getField(), putBlob(), 
        putField()

        getBlob() with string arg now has form returning the string
        (rather than Retcode)

    x Added deleteTableIfExists()
  950523
    x Added getAliasName(), getTableName()
  950520
    x Changed TBDatabase::endTransaction() to not take trx handle arg any
        longer
    x TQuery functions' interface that return references to TBRecord and 
        TBCursor pointers may be changed in the future to a returned
        object instead.
    x EBool enum name changed to TBoolean
    x winout definition no longer required by TQuery class
    x IDE file compiles to .LIB files, like KDBF

Compile instructions (assuming use of BC IDE):

1) Add to project the following .lib file:
    \bde\lib\tdbfdwlv.lib  (if large, dynamic RTL, debug info on model)

2) Add to Options->Project->Directories:
    Include: \bde\examples\tdbf\include

- - - -
The following functionality is added to the KDBF:
  -Exception objects thrown to caller on many errors
  -XPRIM primary-index name suffix support for PDOX<->IB portability
  -appendTable() supports source, dest. cursors
  -createTableBorrow() creates local tbl, borrowing remote tbl struct
  -sortTable() sorts an unkeyed local table to itself
  -copyToSimilar() copies one record buffer to another by field name

  A TQuery class is also included, which does the following:
  -Query may be passed in either strstream or string arg
  -Query result may be returned to either a cursor or a (local) table
  -If a cursor return, TBCursor, TBRecord allocate/deallocate is managed
    by constructor/destructor

- - - -
-end-

