TRecSet

Source: source/classes/trecset.prg — Since FWH 14.07

TRecSet is FiveWin's wrapper around ADO (ActiveX Data Objects) RecordSet objects. It provides a Harbour-friendly interface to access any data source supported by ADO providers -- including Microsoft Access (.mdb/.accdb), SQL Server, Excel files, and any OLE DB-compatible database. TRecSet uses TOleAuto internally to communicate with the ADODB.RecordSet COM object.

flowchart LR subgraph "Harbour Application" A[TRecSet] end subgraph "COM Layer" B[TOleAuto
ADODB.RecordSet] C[ADODB.Connection] end subgraph "Data Sources" D[Access .mdb/.accdb] E[SQL Server] F[Excel .xls/.xlsx] G[Any OLE DB Provider] end A --> B B --> C C --> D C --> E C --> F C --> G

Key DATA Members

DATA	Type	Description
`oRs`	TOleAuto	The underlying ADODB.RecordSet COM object
`aStruct`	Array	Field structure array (compatible with DbStruct())
`cTable`	Character	Source table name
`lReadOnly`	Logical	Read-only access mode
`lFound`	Logical	Result of last Seek/Find operation
`lPadRead`	Logical	Pad character fields to full length on read
`lTrimRead`	Logical	Trim character fields on read
`hFieldPos`	Hash	Hash of field names to positions (case-insensitive)
`bEdit`	Block	Code block for record editing
`cDBMS`	Character	Database management system name

Class DATA

CLASSDATA	Description
`DefaultConnection`	Default ADO connection for all new instances
`AllMsgAsFields`	Treat message names as field names (default `.T.`)
`nMemoSizeLimit`	Fields wider than this are treated as memo (default 80)

Methods

Method	Description
`New( oRs, cSql, oCn, nCursorType, nLockType )`	Create TRecSet from existing RecordSet, SQL, or connection
`Open( cSql, oCn, nCursorType, nLockType, nOpt )`	Open the RecordSet with SQL query or table name
`Close()`	Close the RecordSet
`End()`	Close and release the RecordSet object
`FieldGet( uFld )`	Get field value by name or position
`FieldPut( nFld, uValue )`	Set field value
`FieldPos( cFld )`	Get field position by name
`FieldName( nFld )`	Get field name by position
`FieldType( ncFld, cNew )`	Get/set field type
`FieldLen( ncFld, nNew )`	Get/set field length
`FieldDec( ncFld, nNew )`	Get/set field decimal places
`FieldPic( ncFld, cNewPic )`	Get/set field picture format
`FCount()`	Number of fields
`Save( nStatus )`	Save pending changes to the record
`Commit()`	Commit transaction
`Delete()`	Delete current record
`Append( aCols, aVals )`	Add a new record with optional field values
`Seek( uSeek, lSoft, lWildSeek )`	Search for a value in the current sort order
`Find()`	Find record matching criteria (alias for Locate)
`SetOrder( cOrder )`	Set sort order (SQL ORDER BY syntax)
`SetFilter( c )`	Set ADO recordset filter
`ClearFilter()`	Remove filter
`MoveFirst() / MoveLast() / MoveNext() / MovePrevious()`	Record navigation
`GoTop() / GoBottom() / Skip( n )`	DBF-compatible navigation
`RecordCount()`	Total number of records
`RecNo() / GoTo( n )`	Bookmark-based positioning
`SetXBrowse( oBrw, aCols, lAutoSort, lAddCols )`	Bind to XBrowse with automatic column setup

Example: Open SQL and Bind XBrowse

#include "FiveWin.ch"

function Main()

   local cConn, oRs, oWnd, oBrw

   cConn := "Provider=SQLOLEDB;" + ;
            "Data Source=MYSERVER\SQLEXPRESS;" + ;
            "Initial Catalog=Northwind;" + ;
            "Integrated Security=SSPI"

   oRs := TRecSet():New( , "SELECT * FROM Products ORDER BY ProductName", cConn )
   oRs:Open()

   DEFINE WINDOW oWnd TITLE "Products"

   @ 0, 0 XBROWSE oBrw OF oWnd AUTOSORT
   oRs:SetXBrowse( oBrw, , .T. )
   oBrw:CreateFromCode()

   ACTIVATE WINDOW oWnd MAXIMIZED

   oRs:End()

return nil

Example: Edit Records

#include "FiveWin.ch"

function Main()

   local oRs := TRecSet():New( , "SELECT * FROM Customers", ;
                    "Provider=Microsoft.ACE.OLEDB.12.0;Data Source=C:\data\mydb.accdb" )
   oRs:Open()

   oRs:MoveFirst()
   ? "Company:", oRs:FieldGet( "CompanyName" )

   // Edit a field
   oRs:FieldPut( "Phone", "555-0100" )
   oRs:Save()

   // Append a new record
   oRs:Append( { "CompanyName", "City" }, { "NewCo Ltd.", "New York" } )

   oRs:End()

return nil

ADO Provider Priority Chains

TRecSet auto-detects the best available OLE DB provider for each RDBMS when a connection string does not specify a provider explicitly. The framework tries providers in priority order, selecting the first one that is installed on the system:

RDBMS	Priority Chain (highest to lowest)
SQL Server	`MSOLEDBSQL` → `SQLNCLI11` → `SQLNCLI10` → `SQLNCLI` → `SQLOLEDB`
MySQL ODBC	`8.3` → `8.0` → `5.3` → `5.2w` → `5.1` → `3.51`
Oracle	`OraOLEDB.Oracle` → `MSDAORA`
PostgreSQL	`PostgreSQL OLE DB Provider`
SQLite	`Microsoft OLE DB Provider for ODBC Drivers` → `SQLite3 ODBC Driver`

Use FW_RDBMSName( oCn ) to detect the active RDBMS after a connection has been established. This function returns a string identifying the database management system currently in use, which is useful for writing portable code that adapts SQL syntax or provider-specific features at runtime.