Native Handles

Native handles allow you to bypass BDE functions to use native SQL database APIs to create and manipulate tables. This approach can deliver substantial performance improvement.

For example, to get a native database handle from a SQL database, you would use this code (assuming you have already obtained a valid handle hDb to an existing SQL database):

--------------

UINT16          Size;

hDBIDb          hDb;

UINT32          hNativeDb

 

DbiGetProp(hDb, dbNATIVEHNDL, &hNativeDb, sizeof(hNativeDb), &Size);

 

A native handle to the SQL database is returned in &hNativeDb and the size in bytes in &Size. Now you can execute native API calls for the SQL database.

The following table shows the information that is available for each driver when using dbNATIVEHNDL, dbNATIVEPASSTHRUHNDL, stmtNATIVEHNDL, or curNATIVEHNDL with DbiGetProp.

dbNATIVEHNDL, dbNATIVEPASSTHRUHNDL

stmtNATIVEHNDL, curNATIVEHNDL

When SQLPASSTHRU MODE is NOT SHARED, the native handles returned from DbiGetProp with dbNATIVEHNDL and dbNATIVEPASSTHRUHNDL will be different. Certain drivers (for example, Sybase) may open multiple connections for one call to DbiOpenDatabase  Only the main native connection handle is available.

Although the native connection and statement handles are always available when there is an active connection or statement, the native cursor handle may not always be available. For example: When working with a "dead" (snapshot) cursor, SQL Links caches each record as it is fetched from the server cursor. When all the records have been fetched, the server cursor is closed and it is no longer available. An attempt to retrieve the native cursor handle by using DbiGetProp with curNATIVEHNDL will return the error, DBIERR_OBJNOTFOUND.

Additional information on the native handle and its use is available from the SQL server vendors.