TDatabase

Source: source/classes/database.prg

TDatabase is FiveWin's object-oriented wrapper around Harbour's DBF/RDD (Replaceable Database Driver) system. It encapsulates all common database operations -- opening, navigating, editing, filtering, indexing, and more -- into a clean class interface. TDatabase can work with any RDD supported by Harbour, including DBFCDX, DBFNTX, DBFNSX, and ADS (Advantage Database Server).

Architecture

Key DATA Members

Constructors

New()

METHOD New( ncArea, cFile, cDriver, lShared, lReadOnly, cPassword )

Creates a TDatabase object. If ncArea is a number or alias of an already-open work area, TDatabase wraps the existing area. If ncArea is a file path string, it prepares to open that file. If only one parameter is passed, it auto-detects whether it is an area number, alias, or filename.

Open()

METHOD Open( cAlias, cFile, cDriver, lShared, lReadOnly, cPassword )

Opens a DBF file with explicit alias. This is the preferred constructor for opening new files.

Create()

METHOD Create( cFile, aStruct, cDriver, cIndexFields, cPassword )

Creates a new DBF file with the specified structure and optionally creates an index. The aStruct parameter is an array of field definitions, where each element contains { cFieldName, cType, nLen, nDec }. The optional cIndexFields parameter specifies a comma-separated list of field names for an automatic index. After creation, the table is opened and the work area is ready for use.

Navigation Methods

Seeking & Filtering

METHOD Seek( uExpr, lSoft, lWildSeek, lCurRec )
METHOD SetFilter( cFilter, aParams )
METHOD ClearFilter()
METHOD SetScope( uTop, uBot )
METHOD SetOrder( cnTag, cFile )
METHOD OrdDescend( cnTag, cFile, lDesc )

Seek() searches the active index for the specified key expression. lSoft enables soft-seek (nearest match). SetFilter() accepts a filter expression string with optional parameter substitution via aParams. SetScope() sets top and bottom scope values to restrict navigation within an index range.

Editing Methods

Locking Methods

Indexing Methods

Buffering

TDatabase supports optional record buffering for optimistic concurrency control. When buffering is enabled, changes are held in memory and written to disk only when Save() is called.

Editing with TDataRow

The Record() method provides a shortcut to create a TDataRow object for the current record, enabling rich editing dialogs:

METHOD Record( cFieldList, lBlank ) -> oDataRow

Pass a comma-separated field list to limit the visible fields, or lBlank=.T. to start with a blank record. The returned TDataRow can be used with Edit() to display an interactive editing dialog:

oDb:GoTop()
oRow := oDb:Record()
if oRow:Edit( , , "Edit Customer" )
   MsgInfo( "Changes saved" )
endif

See TDataRow for full documentation.

Browsing & XBrowse

METHOD Browse( cTitle, acFields )
METHOD SetXBrowse( oBrw, aCols, lAutoSort, lAutocols )
METHOD xBrowse( oWnd, aCols, lAutoSort, bSetUp )

xBrowse() is the quickest way to display database contents in an XBrowse grid. It automatically configures the browse with column headers, data types, and sorting.

Data Flow

Example: Basic DBF Operations

#include "FiveWin.ch"

function Main()

   local oDb, oWnd

   // Open a DBF file with DBFCDX driver
   DATABASE oDb FILE "customers.dbf" DRIVER "DBFCDX" SHARED

   // Equivalent to:
   // oDb := TDatabase():Open( "CUST", "customers.dbf", "DBFCDX", .T. )

   // Navigate
   oDb:GoTop()
   ? oDb:FieldGet( "FIRST" )    // "John"
   ? oDb:FieldGet( "LAST" )     // "Smith"
   ? oDb:hRec[ "FIRST" ]        // "John" (hash access)

   // Set an index order and seek
   oDb:SetOrder( "LAST" )
   if oDb:Seek( "Jones" )
      ? "Found:", oDb:FieldGet( "FIRST" ), oDb:FieldGet( "LAST" )
   endif

   // Edit a record
   if oDb:RecLock()
      oDb:FieldPut( "PHONE", "555-1234" )
      oDb:UnLock()
   endif

   // Append a new record
   oDb:Append()
   oDb:FieldPut( "FIRST", "Jane" )
   oDb:FieldPut( "LAST",  "Doe" )
   oDb:FieldPut( "PHONE", "555-5678" )
   oDb:Save()

   // Apply a filter
   oDb:SetFilter( "STATE = 'CA'" )
   oDb:GoTop()
   do while ! oDb:Eof()
      ? oDb:FieldGet( "FIRST" ), oDb:FieldGet( "LAST" )
      oDb:Skip()
   enddo
   oDb:ClearFilter()

   oDb:Close()

return nil

Example: Browse with XBrowse

#include "FiveWin.ch"

function Main()

   local oDb, oWnd, oBrw

   DATABASE oDb FILE "customers.dbf" DRIVER "DBFCDX" SHARED

   DEFINE WINDOW oWnd TITLE "Customer Browser"

   oDb:xBrowse( oWnd,, .T., { |oBrw|
      oBrw:cHeaders := { "First Name", "Last Name", "Phone", "State" }
      oBrw:lRecordSelector := .F.
   } )

   ACTIVATE WINDOW oWnd MAXIMIZED

   oDb:Close()

return nil

Example: Buffered Editing

#include "FiveWin.ch"

function Main()

   local oDb

   DATABASE oDb FILE "customers.dbf" DRIVER "DBFCDX" SHARED

   // Enable buffering for optimistic locking
   oDb:SetBuffer( .T. )

   oDb:GoTop()

   // Changes go to buffer, not disk
   oDb:FieldPut( "PHONE", "555-0000" )

   if MsgYesNo( "Save changes?" )
      oDb:Save()        // writes buffer to disk
   else
      oDb:RollBack()    // discard changes
   endif

   oDb:Close()

return nil

Example: Creating Indexes

#include "FiveWin.ch"

function Main()

   local oDb

   DATABASE oDb FILE "customers.dbf" DRIVER "DBFCDX" SHARED

   // Create a compound index with multiple tags
   oDb:CreateIndex( "customers.cdx", "NAME",  "UPPER(LAST)+UPPER(FIRST)" )
   oDb:CreateIndex( "customers.cdx", "STATE", "STATE" )
   oDb:CreateIndex( "customers.cdx", "PHONE", "PHONE", .T. )  // unique

   // Use the NAME order
   oDb:SetOrder( "NAME" )
   oDb:GoTop()

   // Scoped navigation: only records where STATE = "CA"
   oDb:SetScope( "CA", "CA" )
   oDb:GoTop()
   do while ! oDb:Eof()
      ? oDb:FieldGet( "LAST" )
      oDb:Skip()
   enddo

   oDb:Close()

return nil

RecordSet-Compatible Syntax

TDatabase provides ADO RecordSet-compatible method names for easier migration between local DBF and remote data:

See Also

• Classes Alphabetical
• Functions