FastX SQL drivery

FastX server implementuje vlastní SQL rozhraní, které je k dispozici jak X modulům prostřednictvím xsql* operátorů, tak FastX pluginům, tedy rozšiřujícím dynamicky linkovaným knihovnám. FastX SQL se opírá o SQL drivery, což jsou normalizovaná rozhraní na jednotlivé typy zdrojů dat. Mají podobu dynamicky linkovaných knihoven, které se registrují v inicializačním bloku init|sql_drivers.

Logicky je FastXSQL rozděleno do dvou základních entit: SQL connection a SQL cursor. SQL connection vytváří tzv. transaction scope, tedy spojení s SQL serverem z hlediska transakcí izolované od dalších spojení. SQL cursor je objekt v rámci SQL connection, který představuje kontext jednotlivého SQL příkazu. V rámci jednoho SQL spojení může existovat několik kurzorů. Jejich maximální počet je sice implementačně závislý, neměl by však být omezujícím faktorem ( Centura SQLBase podporuje 99 kurzorů/ spojení ).

Ukončení transakce, tedy Commit() anebo Rollback() ovlivní všechny kurzory v rámci daného SQL spojení, neboť jsou v kontextu jediné transakce.

SQL drivery musí důsledně podporovat multithreading, stejně jako vlastní FastX server. Implementuje-li SQL driver rozhraní na single-threaded SQL klienta, musí použít synchronizační nástroje OS k zaručení výlučného přístupu.

 

Interface

 Následující sadu funkcí musí SQL driver exportovat:

extern "C"

{

void WINAPI FXSQL_InitDriver();

FastX server volá tuto funkci po natažení driveru do systému. Je vyhrazena pro inicializaci driveru.

void WINAPI FXSQL_FreeDriver();

FastX server volá tuto funkci před uvolněním driveru ze systému. Je vyhrazena pro úklid.

int WINAPI FXSQL_TestCapabilities( int capabilities );

funkce vrátí bitovou masku, která je logickým součinem masky capabilities, tedy zjišťovaných vlastností, a skutečných vlastností driveru. Existují tři vlastnosti:

BOOL WINAPI FXSQL_CanConnect( PCHAR sConnectString );

funkce vrátí true, pokud driver dokáže připojit databázi definovanou connect stringem ( formát <DB>/<USER>/<PWD> ).

FXSQLCONNECTION WINAPI FXSQL_Connection( PCHAR sConnectString, int * errnum );

funkce vrátí identifikátor SQL spojení, pokud se podařilo připojit k databázi zadaným uživatelským profilem definovaným connect stringem ( formát <DB>/<USER>/<PWD> ), jinak -1 a *errnum obsahuje interní kód chyby.

FXSQLCURSOR WINAPI FXSQL_DeriveCursor( FXSQLCONNECTION conn, int * errnum );

funkce vrátí identifikátor SQL kurzoru, pokud se podařilo jej připojit v kontextu zadaného SQL spojení, jinak -1 a *errnum obsahuje interní kód chyby.

int WINAPI FXSQL_Prep( FXSQLCURSOR conn, PCHAR command );

funkce připraví SQL příkaz v kontextu daného SQL kurzoru.

int WINAPI FXSQL_Ret( FXSQLCURSOR conn, PCHAR cmdname );

funkce připraví SQL uloženou proceduru v kontextu daného SQL kurzoru.

int WINAPI FXSQL_Exec( FXSQLCURSOR conn );

funkce vyvolá dříve připravený SQL příkaz anebo uloženou proceduru v kontextu daného SQL kurzoru.

int WINAPI FXSQL_PrepAndExec( FXSQLCURSOR conn, PCHAR command );

funkce připraví a vyvolá dříve SQL příkaz anebo uloženou proceduru v kontextu daného SQL kurzoru.

int WINAPI FXSQL_Commit( FXSQLCONNECTION conn, FXSQLCURSOR cursor );

funkce potvrdí transakci v kontextu daného SQL spojení.

int WINAPI FXSQL_Rollback( FXSQLCONNECTION conn, FXSQLCURSOR cursor );

funkce odvolá transakci v kontextu daného SQL spojení.

void WINAPI FXSQL_ErrorInfo( FXSQLCONNECTION conn, FXSQLCURSOR cursor, int * errnum, int * errpos );

funkce vrátí informace o poslední chybě na adném SQL kurzoru a/nebo spojení (nebyl-li kurzor připojen).

void WINAPI FXSQL_ErrorText( FXSQLCONNECTION conn, FXSQLCURSOR cursor , char * buffer, int buflen );

funkce zapíše do textového bufferu informace o poslední chybě na adném SQL kurzoru a/nebo spojení (nebyl-li kurzor připojen).

int WINAPI FXSQL_Bind( FXSQLCURSOR cursor, COLUMN_ORDER order, PCHAR buffer, int length, unsigned char bind_var_type );

funkce nahradí symbolický parametr v 'připraveném' SQL příkazu skutečnou hodnotou. Je volána právě jednou pro každý parametr SQL příkazu.

int WINAPI FXSQL_AutoInto(FXSQLCURSOR cursor );

funkce má za úkol inicializovat fetch buffer, tedy paměť, do které se uloží 1 řádka dat přečtená funkcí FXSQL_Fetch*().

void WINAPI FXSQL_AutoIntoClear( FXSQLCURSOR cursor, FXSQLAUTOINTO auto_into );

funkce má za úkol uvolnit z paměti fetch buffer.

void WINAPI FXSQL_AutoIntoSetDatePic( FXSQLCURSOR cursor, FXSQLAUTOINTO auto_into, const char * auto_into_date_pict );

funkce má za úkol nastavit formát datumu, který bude respektován při čtení dat.

void WINAPI FXSQL_AutoIntoSetDateTimePic( FXSQLCURSOR cursor, FXSQLAUTOINTO auto_into, const char * auto_into_datetime_pict );

funkce má za úkol nastavit formát datumu a času, který bude respektován při čtení dat.

char * WINAPI FXSQL_AutoIntoValue(FXSQLCURSOR cursor, FXSQLAUTOINTO auto_into, COLUMN_ORDER order );

funkce má za úkol vrátit adresu hodnoty požadovaného sloupce v řádku aktuálně vytaženém funkcí FXSQL_Fetch*().

int WINAPI FXSQL_Fetch(FXSQLCURSOR cursor, long nRow );

funkce má za úkol vytáhnout z result setu spuštěného SQL příkazu zadaný řádek. První řádek má číslo 0.
Návratové hodnoty:0=Ok, 1=End Of Fetch, 2=row modified, jinak kód chyby

int WINAPI FXSQL_FetchNext(FXSQLCURSOR cursor, long nRow );

funkce má za úkol vytáhnout z result setu spuštěného SQL příkazu následující řádek.
Návratové hodnoty:0=Ok, 1=End Of Fetch, 2=row modified, jinak kód chyby

int WINAPI FXSQL_SelectItemCount( FXSQLCURSOR cursor, FXSQLAUTOINTO auto_into );

funkce má za úkol vrátit počet sloupců SQL selectu.

int WINAPI FXSQL_SelectItemInfo( FXSQLCURSOR cursor, FXSQLAUTOINTO auto_into, COLUMN_ORDER order, PDATATYPE pdt, PDATALEN pdl, PDATALEN pdec, char * labelBuffer128 );

funkce má za úkol zjistit informace o zadaném sloupci SQL selectu (datový typ, délka, počet des. míst, jméno sloupce/výraz - max. 127 znaků!!!).

int WINAPI FXSQL_SelectItemCount( FXSQLCURSOR cursor, FXSQLAUTOINTO auto_into );

funkce má za úkol vrátit počet sloupců SQL selectu.