HDBC RDD (Replaceable Database Driver) Reference Manual

[xmanuel]

HDBC RDD (Replaceable Database Driver) Reference Manual

The HDBC RDD (RDDHDBC) is a powerful engine allowing Harbour developers to interact with any HDBC-connected SQL database uniformly mapping classic xBase commands (USE, APPEND BLANK, REPLACE, SKIP, SEEK, SET FILTER, etc.).

This bridging layer translates your procedural legacy operations dynamically down into native dialects fitting your configured backing engine (SQLite, MySQL, PostgreSQL, etc.). It acts as a perfect gateway for porting existing applications or satisfying developers refusing direct object-oriented manual SQL interactions.

--- 1. Initial Setup and Driver Injection

To begin leveraging WorkAreas, bind your globally instantiated THDbc connection underlying the Harbour core RDD subsystem.

Code: Select all | Expand

#include "hdbc_conn.ch"
#include "hdbc.ch"
#include "rddsys.ch"

PROCEDURE Main()
   LOCAL oDbc := THDbc():new( HDBC_DRIVER_SQLITE )
   
   oDbc:connect( "database=test_rdd.db" )
   
   // 1. Register the core architecture internally
   rddRegister( "RDDHDBC", RDT_FULL )
   
   // 2. Cascade your active connection stream down to the RDD scope
   HDbcRdd_Init( oDbc )
   
   // 3. (Optional) Force all standard commands to ride this driver
   RddSetDefault( "RDDHDBC" )

[!TIP]
Before terminating the system scope gracefully, wipe unreleased states utilizing HDbcRdd_End() before concluding THDbc disconnect logic.

--- 2. Basic xBase Operations (CRUD) 2.1 Table Generation (dbCreate)

You can architect remote structures directly by feeding a standard structural array blueprint extended with the specialized TIMESTAMP type natively.

Code: Select all | Expand

LOCAL aStruct := { ;
   { "ID",      "N", 10, 0 }, ;
   { "NAME",    "C", 50, 0 }, ;
   { "SALARY",  "N", 12, 2 }, ;
   { "DATE",    "D",  8, 0 }, ;
   { "ACTIVE",  "L",  1, 0 }  ;
} 

dbCreate( "employees", aStruct, "RDDHDBC" )

2.2 WorkArea Allocation (USE)

Code: Select all | Expand

USE employees ALIAS EMP VIA "RDDHDBC" NEW

IF NetErr()
   ? "Server failed handling remote table mount"
ENDIF

2.3 Insertion (APPEND BLANK & REPLACE)

Code: Select all | Expand

SELECT EMP
APPEND BLANK
REPLACE FIELD->ID      WITH 1, ;
        FIELD->NAME    WITH "John Doe", ;
        FIELD->SALARY  WITH 2500.50, ;
        FIELD->ACTIVE  WITH .T.

2.4 Navigation (dbSkip, EOF, BOF)

Code: Select all | Expand

EMP->( dbGoTop() )
DO WHILE ! EMP->( Eof() )
   ? "ID:", EMP->ID, "Name:", EMP->NAME
   EMP->( dbSkip() )
ENDDO

2.5 Dropping Logic (Physical vs Logical)

Whenever the inner schema observes standard deletion columns (SoftDeletes flag logic), the underlying DELETE routing overrides to UPDATE. Otherwise conventional physically dropping DELETE FROM execution applies natively preventing disk pollution.

Code: Select all | Expand

GOTO 2
DELETE
? "Target instance stripped. Deleted():", Deleted()

--- 3. Advanced Remote Features 3.1 Fetch Scopes (INDEX ON & dbSeek)

Create runtime virtual indexing to hasten binary narrowing avoiding sequentially linear sweeps.

Code: Select all | Expand

USE clients ALIAS CLI NEW VIA "RDDHDBC"
INDEX ON FIELD->name TAG query_name

SEEK "Maria Garcia"
IF Found()
   ? "MATCHED ALIAS! ID:", CLI->id, "City:", CLI->city
ENDIF

3.2 Condition Restricting (SET FILTER & SCOPES)

While SET FILTER inherently navigates evaluating record by record, HDBC naturally honors index SCOPES thresholds. Scoping performs logarithmically faster because it intervenes during the early native pre-generation injecting boundaries straight into the SQL request.

Usage of SET FILTER:

Code: Select all | Expand

SET FILTER TO CLI->city == "London"
GO TOP
DO WHILE ! Eof()
   ? "Located resident:", CLI->name
   SKIP
ENDDO
SET FILTER TO // Purge constraint

Usage of SCOPES (Smart Indexing Bounds):

Code: Select all | Expand

// Assuming an 'idx_city' tag is created...
ORDSETFOCUS( "idx_city" )
// Lock bounds for TOP (0) and BOTTOM (1)
ORDSCOPE( 0, "London" )
ORDSCOPE( 1, "London" )

GO TOP
// Loop traverses exclusively limited London bounds at lightning speed
ORDSCOPE( 0, NIL ) // Revert top bound wipe out

3.3 Foreign Relational Mapping (SET RELATION)

Enforce runtime cascading pointers syncing chained aliases asynchronously while advancing parent cursors step-by-step parallelizing child targets seamlessly.

Code: Select all | Expand

USE invoices ALIAS INV NEW VIA "RDDHDBC"

SELECT CLI
INDEX ON FIELD->id TAG idx_cli

SELECT INV
SET RELATION TO INV->client_id INTO CLI

GO TOP
DO WHILE ! Eof()
   // Background translation fetches matching row
   ? "Order Number:", INV->id, "-> Pertaining Client:", CLI->name
   SKIP
ENDDO

3.4 Raw DML Aliasing ("SQL-as-Table")

Probably representing RDDHDBC heaviest lifting trick allowing you to package highly volatile aggregated queries directly transforming results wrapping around purely readable WorkAreas.

Code: Select all | Expand

USE "SELECT c.name, COALESCE(SUM(i.total), 0) as subtotal FROM clients c LEFT JOIN invoices i ON c.id = i.client_id GROUP BY c.id, c.name" ALIAS REPORT NEW VIA "RDDHDBC"

IF Used()
   DO WHILE ! Eof()
      ? "Ledger stats:", REPORT->name, "Subtotal:", REPORT->subtotal
      SKIP
   ENDDO
   CLOSE REPORT
ENDIF

--- 4. Concurrency Flow

Native RDDHDBC logic heavily relies upon the initialized driver bounds.

Transaction Wrapping

Utilize master oDbc object hooks enclosing blocks strictly honoring RDMS ACID specifications.

Code: Select all | Expand

oDbc:beginTrans()

REPLACE SEC->balance WITH SEC->balance + 500

IF lSuccess
   oDbc:commit() 
ELSE
   oDbc:rollback()
ENDIF

--- 5. Physical Maintenance (PACK and ZAP)

RDDHDBC flawlessly couples Harbour legacy maintenance commands with strict backend architectural standards.

ZAP (Full Truncate)

By invoking ZAP, the RDD driver will omit any standard linear DELETE FROM protocol SQL clauses, issuing a definitive native TRUNCATE TABLE command into the targeted engine instead. It resets the database without unnecessarily choking transaction logs (substantially faster).

Code: Select all | Expand

USE audit_trails ALIAS AUD VIA "RDDHDBC" EXCLUSIVE
ZAP
? "Audit table radically truncated back to pristine conditions."

PACK (SoftDelete Flushing/Purging)

In traditional DBFs, PACK compacted empty binary slots sequentially. Within HDBC, if an active session flags "Logical Deletion" features (possessing a compliant trailing deleted_at column), issuing the DELETE command exclusively yields Soft-Deletes modifying the date stamp, leaving real data securely attached remotely.
Enacting the PACK command orchestrates the definitive heavy-duty SQL statement dropping permanently any row previously marked with the logical deletion timeframe, fulfilling purely compliant 1:1 xBase replication workflows.

Code: Select all | Expand

USE clients ALIAS CLI VIA "RDDHDBC" EXCLUSIVE
PACK 
? "Database thoroughly sanitized definitively dropping hidden soft-deleted entries."

Soft Targeting Locks

Optionally leverage standard RLock() to tentatively deny writes targeting your mutating tuples if your engine dialect fully orchestrates external transaction locks locking records atomically safely.

Code: Select all | Expand

GO TOP
IF RLock()
   REPLACE SEC->balance WITH 2000
   UNLOCK
ELSE
   ? "Overlapping constraint violation. Process stalled remotely."
ENDIF

And this works with: MySQL, MariaDB, SQLite and clones, Postgres, Oracle, SQLServer, Interbase, Firebird and ODBC. Writing a PRG for any database is now a reality!!!

[TimStone]

1). Based on what I see here, this does not appear to be compatible with the tDatabase class.
2). Where is HDBC RDD available ?

I think it is a very nice addition to our community, but all of my data access is now through data classes using tDatabase.

Tim

[xmanuel]

Hi Tim,

Great news on the tDatabase front! HDBC RDD is a fully standard Harbour RDD, meaning it behaves exactly like any other RDD. Since tDatabase is a layer built on top of standard DB-style commands (DBUseArea(), DBSkip(), DBGoTo(), etc.), it should work with HDBC RDD without any issues at all.

But here is the exciting part — HDBC is actually much more than just an RDD:

1) It includes a built-in ORM that could serve as a direct replacement for tDatabase, offering a modern, object-oriented way to work with your data.

2) It also provides direct database access, bypassing the RDD layer entirely. This is the recommended approach if you really want to get the most out of the library — better performance, full SQL expressiveness, and tighter control over your data access.

I think once you see all three layers together you will find there is a fit for every part of your application.

I would love to have a deeper conversation about this. Could you share your email address so we can continue this discussion in more detail?

Best regards

[TimStone]

[email protected]