Suportul bazei de date - CDatabase

Un obiect CDatabase reprezinta o conexiune la sursa de date, prin care se poate opera cu sursa de date. O sursa de date este specifica unei instante administrata de un sistem de management al bazelor de date (DBMS). Exemple ar fi Microsoft SQL Server, Microsoft Access,Borland dBASE si XBASE. Pot fi mai multe baze de date active în cadrul aceleeasi aplicatii.

MFC furnizeaza suport bazelor de date cu conexiune ODBC prin clasele CDatabase si CRecordset. Pentru a folosi CDatabase, se 959j99j construieste un obiect CDatabase si se apeleaza functia membru OpenEx. Aceasta deschide conexiunea. Când sunt construite obiectele CRecordset pentru operare pe sursa de date la care aplicatia are acces, constructorul recordset-ului trimite un pointer la un obiect CDatabase.

Membrii clasei CDatabase

Date membru

m_hdbc - contine un handler public la o conexiune de date ODBC, tip HDBC. În mod normal, nu va fi nevoie ca aceasta variabila membru sa fie accesata direct. Framework-ul aplicatiei aloca acest handler prin apelarea functiei OpenEx sau Open si dealoca handler-ul prin apelarea operatorului de stergere al clasei CDatabase. De notat ca functia membru Close nu dealoca handler-ul.

În cazul în care ar fi nevoie de apelarea unei functii ODBC API în mod direct si nu prin clasa CDatabase, s-ar putea sa fie nevoie ca handler-ul sa fie folosit ca parametru. Iata un exemplu:

// m_db este obiectul CDatabase; m_hdbc este

// variabila HDBC

nRetcode = ::SQLGetInfo( m_db.m_hdbc,

SQL_ODBC_SQL_CONFORMANCE,

&nValue,

sizeof( nValue ),

&cbValue );

Construirea unui obiect CDatabase

CDatabase - construieste un obiect CDatabase, initializarea facându-se cu ajutorul OpenEx sau Open si de asemenea se face si conectarea la sursa de date. Este convenabil ca în cadrul unei clase de tip CDocument sa avem acces la o baza de date. Iata un exemplu :

// Acest exemplu arata folosirea CDatabase

// într-o clasa derivata din CDocument.

class CMyDocument : public CDocument

// Initializare

CDatabase* CMyDocument::GetDatabase( )

Open stabileste conexiunea la sursa de date.

virtual BOOL Open( LPCTSTR lpszDSN, BOOL bExclusive = FALSE, BOOL bReadOnly = FALSE, LPCTSTR lpszConnect = "ODBC;", BOOL bUseCursorLib = TRUE );

throw( CDBException, CMemoryException );

Functia returneaza o valoare nenula daca s-a facut conexiunea, altfel returneaza 0 daca utilizatorul alege optiunea Cancel în momentul când îi este afisata o caseta de dialog cu informatii de conectare la sursa de date. În ambele cazuri, framework-ul genereaza  o exceptie.

lpszDSN - specifica numele sursei de date, nume înregistrat cu ODBC prin ODBC Administrator. Daca valoarea DSN-ului este specificata în lpszConnect (în forma "DSN=<sursa de date>"), ea nu mai trebuie specificata si în lpszDSN, care ar trebuie sa fie NULL. Altfel, poate fi lasat lpszDSN la valoarea NULL daca se doreste ca utilizatorului sa îi fie prezentata caseta de dialog cu toate sursele de date din care poate alege.

bExclusive - nu are suport în aceasta versiune a clasei. O operatie de asertie esueaza daca acest parametru este setat pe valoarea TRUE. Sursa de date este deschisa întotdeauna neexclusiv.

bReadOnly - este setat pe valoarea TRUE daca se intentioneaza o conexiune doar cu drept de citire. Toate înregistrarile mostenesc acest atribut. Valoarea prestabilita este FALSE.

lpszConnect - specifica un sir de conectare. sirul de conectare concateneaza informatia, cu posibilitate de includere a numelui unei surse de date, a unui ID valid pentru sursa de date, o autentificare a utilizatorului (parola, daca sursa de date o necesita), sau alte informatii. sirul de conectare trebuie sa fie prefixat de sirul "ODBC;". sirul "ODBC;" este folosit pentru a se indica daca o conexiune se face la o sursa ODBC - aceasta este legata de compatibilitatea "upward'' când clasa ar putea suporta surse non-ODBC.

 bUseCursorLib - TRUE daca va fi încarcat ODBC Cursor Library DLL. Biblioteca cursorului ascunde câteva functionalitati ale driverului ODBC, prevenind efectiv folosirea de dynaset-uri. Singurele cursoare suportate în cazul încarcarii acestui DLL sunt cele de tip static snapshot si forward-only. Valoarea initiala este TRUE. Daca se doreste crearea unui obiect CRecordset fara derivare din el, nu se recomanda încarcarea acestui DLL de cursoare.

Daca parametrii functiei Open apelate nu contin suficiente informatii pentru conectare, driverul ODBC afiseaza un dialog pentru a obtine informatiile lipsa.

sirul de conectare poate fi folosit si pentru nivele multiple de conectare (fiecare pentru un obiect CDatabase diferit) sau pentru partajare cu informatia altei surse de date.

Este posibil, pentru o conectare, expirarea timpului daca, de exemplu nu este disponibil DBMS-ul. Daca încercarea de conectare esueaza, Open "arunca o exceptie. Iata un exemplu :

CDatabase m_dbClient( );

// Conectare a unui obiect la

// sursa de date (fara parola)

// dialogul ODBC de conectare

// va ramâne ascuns

m_dbClient.Open( _T( "SURSAMEA" ), FALSE,

FALSE, _T( "ODBC;UID=BOGDAN" ),

// ...sau interogheaza utilizatorul

// pentru orice alta informatie

m_dbClient.Open( NULL );

OpenEx - stabileste o conexiune la sursa de date (prin driver ODBC).

virtual BOOL OpenEx( LPCTSTR lpszConnectString, DWORD dwOptions = 0 );

throw( CDBException, CMemoryException );

Functia returneaza o valoare nenula daca s-a facut conexiunea, altfel returneaza 0 daca utilizatorul alege optiunea Cancel în momentul când îi este afisata o caseta de dialog cu informatii de conectare la sursa de date. In ambele cazuri, framework-ul genereaza o exceptie.

lpszConnectString  - specifica un sir de conectare prin ODBC. Acesta include numele sursei de date ca si alte informatii cum ar fi ID utilizatorului si parola sa. De exemplu, "DSN=SQLServer_Source, UID=SA; PWD=abc123" este un posibil sir de conectare. 

 dwOptions - Un bitmask care specifica o combinatie de valori. Valoarea initiala este 0, însemnând ca baza de date este deschisa pentru scriere, ODBC Cursor Library DLL nu va fi încarcat, iar dialogul conexiunii ODBC nu va fi deschis decât daca nu sunt furnizate informatii suficiente pentru stabilirea conexiunii.

CDatabase::openExclusive. Nu este suportat de aceasta versiune a clasei, sursa de date este deschisa mereu neexclusiv.

CDatabase::openReadOnly.  Deschide sursa de date numai pentru citire. 

CDatabase::useCursorLib. Încarca ODBC Cursor Library DLL.

CDatabase::noOdbcDialog. Împiedica afisarea dialogului ODBC de conectare..

CDatabase::forceOdbcDialog. Afiseaza întotdeauna dialogul ODBC de conectare.

Daca parametrii functiei OpenEx apelate nu contin suficiente informatii pentru conectare, driverul ODBC afiseaza un dialog pentru a obtine informatiile lipsa.

sirul de conectare poate fi folosit si pentru nivele multiple de conectare (fiecare pentru un obiect CDatabase diferit) sau pentru partajare cu informatia altei surse de date.

Este posibil, pentru o conectare, expirarea timpului daca, de exemplu nu este disponibil DBMS-ul. Daca incercarea de conectare esueaza, Open arunca o exceptie. Iata un exemplu :

CDatabase m_dbClient( );

// Conectare a unui obiect la

// sursa de date (fara parola)

// dialogul ODBC de conectare

// va ramane ascuns

m_dbClient.OpenEx( _T( "DSN=SURSAMEA;UID=BOGDAN" ),

CDatabase::openReadOnly |

CDatabase::noOdbcDialog ) );

Close - inchide conexiunea la sursa de date. Se apeleaza aceasta functie cand se doreste deconectarea de la sursa de date. Trebuiesc inchise toate inregistrarile asociate cu obiectul CDatabase inainte de apelarea acestei functii. Toate operatiile de adugare sau editare a inregistrarilor, cat si tranzactiile sunt anulate. Inregistrarile dependente de obiectul CDatabase raman in stare nedefinita. Iata un exemplu :

m_dbClient.Close( );

// Posibila o conectare a obiectului la alta sursa de date

m_dbClient.OpenEx("DSN=SURSAMEA;UID=BOGDAN");

Atribute ale bazei de date

GetConnect returneaza sirul de conectare asociat unui obiect CDatabase, furnizat de apelul functiei Open sau OpenEx - altfel returneaza un sir gol.

IsOpen - returneaza o valoare nenula daca obiectul CDatabase este conectat la o sursa de date.

GetDatabaseName - returneaza, in caz de succes, numele bazei de date intr-un sir. Nu este acelasi lucru cu numele sursei de date (DSN) specificat in apelul Open sau OpenEx. Ceea ce returneaza GetData-BaseName depinde de ODBC. In general, o baza de date este o colectie de tabele. Daca acesta entitate are un nume, functia il returneaza.

CanUpdate - returneaza o valoare nenula daca obiectul CDatabase accepta operatii de update si indica daca bReadOnly a fost setat pe valoa-rea TRUE. Sursa de date este numai pentru citire daca apelul functiei ODBC API :: SQLGetInfo pentru SQL_DATASOURCE_READ_ONLY returneaza "y". 

CanTransact - returneaza o valoare nenula daca sursa de date suporta tranzactii.

SetLoginTimeout - seteaza numarul de secunde pana la expirarea timpului alocat conectarii.

void SetLoginTimeout( DWORD dwSeconds )

dwSeconds  - numarul de secunde setate.

Se apeleaza aceasta functie - inainte de apelul Open sau OpenEx - pentru a suprascrie numarul initial de secunde acordate conectarii. Valoarea initiala este de 15 secunde. Nu toate sursele de date suporta aceasta abilitate de setare a timpului de conectare. Valoarea "0" inseamna infinit. 

SetQueryTimeout seteaza numarul de secunde dupa care opearatiile de interogare a bazei de date sunt oprite. Aceasta afecteaza toate actiunile de deschidere, adaugare, editare si stergere.

void SetQueryTimeout( DWORD dwSeconds )

dwSeconds - numarul de secunde setate.

Se apeleaza aceasta functie pentru a suprascrie numarul initial de secunde acordate operatiilor pe baza de date. In cazul retelelor cu timp de acces mare, acesta functie poate fi de un succes real, prin setarea explicita  unui timp de lucru mai indelungat operatiilor pe baza de date. Schimbarea timpului de lucru nu afecteaza continutul inregistrarilor din baza de date. Valoarea initiala este de 15 secunde. Nu toate sursele de date suporta aceasta abilitate de setare.

GetBookmarkPersistence - Identifica bookmark-urile persistente pe inregistrari, folosind un bitamask.

Daca se apeleaza CRecordSet::GetBookmark si apoi Crecordset::Requery

bookmark-ul obtinut prin aceasta functie nu mai este valid. Urmatorul tabel listeaza bitmask-urile care pot fi combinate cu valoarea de retur a functiei GetBookmarkPersistence.

GetCursorCommitBehavior - identifica efectul comiterii unei tranzactii pe un obiect tip inregistrare.

GetCursorRollbackBehavior - identifica efectul anularii unei tranzactii pe un obiect tip inregistrare.

Operatii in CDatabase

BeginTrans - incepe o tranzactie - o serie de apeluri reversibile pentru adaugare,stergere,editare si update a functiilor membru ale clasei CRecordset prin sursa de date la care aplicatia este conectata.

BOOL BeginTrans( );

Returneaza o valoare nenula daca apelul este cu succes si schimbarile sunt facute manual, altfel returneaza 0. Inainte de inceperea tranzactiei, obiectul CDatabase trebuie sa fie deja conectat la sursa de date prin apelul functiei OpenEx sau Open. Pentru a incheia tranzactia, se apeleaza CommitTrans pentru a fi acceptate toate modificarile sursei de date sau se apeleaza Rollback pentru abandonarea intregii tranzactii.

In functie de driverul ODBC, deschiderea unui recordset inainte de apelul BeginTrans poate cauza probleme la apelul functiei Rollback. De exemplu, cand se foloseste Microsoft Access driver inclus in Microsoft ODBC Desktop Driver Pack 3.0, trebuie stiut ca motorul bazelor de date Jet cere a nu fi inceputa o tranzactie pe o baza de date care are deschisa un cursor. In clasele MFC, un cursor deschis este sinonim cu un obiect CRecordset deschis.

BeginTrans poate de asemenea sa retina inregistrari pe server, in functie de cererile concurentiale si capabilitatile sursei de date.

CommitTrans - completeaza o tranzactie inceputa cu BeginTrans.

BOOL CommitTrans( );

Returneaza o valoare nenula daca apelul este cu succes si schimbarile sunt facute manual, altfel returneaza 0. Daca CommitTrans esueaza, starea sursei de date este nedefinita.

Aceasta functie este apelata dupa completarea unei tranzactii. Update-urile sunt facute imediat.

Rollback - anuleaza schimbarile facute de tranzactia curenta. Sursa de date se intoarce la starea ei anterioara, inainte de apelul functiei BeginTrans.

BOOL Rollback( );

Returneaza o valoare nenula daca apelul este cu succes. Daca Rollback esueaza, starea sursei de date este nedefinita. Daca Rollback returneaza 0, trebuie cercetata sursa de date pentru a i se determina starea.

Dupa apelul Rollback, inregistrarea care era curenta anterior apelului ramine curenta.

Cancel - anuleaza orice operatie asincrona sau orice proces dintr-un al doilea fir de executie. De notat ca clasele MFC ODBC nu mai folosesc procesarea asincrona ; pentru a efectua o operatie asincrona, trebuie apelat direct functia ODBC API SQLSetConnectOption.

ExecuteSQL - executa o instructiune SQL, nu se returneaza in-registrari.

void ExecuteSQL( LPCSTR lpszSQL );

throw( CDBException );

lpszSQL - pointer la un sir terminat cu 0, continind o comanda SQL valida. Se poate trimite un obiect CString.

Se apeleaza acesta functie cand este necesara executia unei comenzi SQL in mod direct. Daca se doreste operarea pe inregistrari, atunci se foloseste un obiect de tip CRecordset si nu aceasta functie.

Majoritatea comenzilor asupra sursei de date sunt evidentiate de obiectele tip inregistrare, care suporta operatii de selectie a datelor, inserare de noi inregistrari, editare de inregistrari. Oricum, nu este suportata intreaga functionalitate a ODBC de clasele bazelor de date din MFC, astfel ca s-ar putea sa fie necesar un apel direct al ExecuteSQL. Iata un exemplu :

CString strCmd = "UPDATE Taxe SET National = 36%";

TRY

CATCH(CDBException, e)

END_CATCH

Membrii care pot fi suprascrisi ai clasei CDatabase

OnSetOptions - functie apelata de catre framework-ul aplicatiei pentru a seta optiunile standard de conectare. Implementarea initiala seteaza valoarea "query timeout".

hstmt - handler-ul ODBC pentru care sunt setate optiunile. Framework-ul apeleaza aceasta functie membru cand se executa o comanda SQL folosind functia membru ExecuteSQL. CRecordset::OnSetOptions procedeaza in mod analog. Daca exista alte apeluri anterioare ale SetQueryTimeout si ale functiei membru de mai sus, OnSetOptions reflecta valorile optiunilor curente, altfel seteaza valorile initiale.

Inainte de MFC 4.2, OnSetOptions seta modul de procesare in sincron sau asincron. Incepand cu MFC 4.2, toate operatiile sunt sincrone. Pentru a efectua o operatie asincrona, trebuie sa fie apelata in mod direct functia ODBC API SQLSetPos.

Nu este necesara suprascrierea functiei OnSetOptions pentru schimbarea valorii timpului de lucru. In schimb, pentru a face acesta schimbare se apeleaza functia SetQueryTimeout inanite de crearea unui recordset. OnSetOptions va folosi noua valoare.

Se suprascrie OnSetOptions daca se doreste o adaugare de optiuni. Suprascrierea va trebui sa apeleze mai intai OnSetOptions din clasa de baza, imediat inainte de apelul functiei ODBC API SQLSetStmtOption. Pentru aceasta se urmeaza modelul ilustrat in implementarea initiala a functiei OnSetOptions a framework-ului.