Delphi - TADOConnection komponens

ADO paletta 2. rész

forráskód letöltése
Bármikor, amikor ADO alkalmazást írunk, az első komponens amit használnunk kell, a TADOConnection. Ebben a cikkben ezt a komponenst vizsgáljuk meg közelebbről. Példaprogram

A mellékelt programban egy ADOConnection komponens segítségével kapcsolatot teremtünk egy adatforrással, és egy ADOTable - DataSource - DBGrid együttes segítségével demonstráljuk, hogy a kapcsolat felépítése sikeres volt. A ConnectionString felépítésekor válasszuk a Jet Providert (Microsoft.Jet.OLEDB.4.0). Így több választási lehetőségünk is van, hogy mihez szeretnénk csatlakozni. A rendelkezésre álló driverek listáját megkereshetjük a Registry-ben a HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Jet\4.0\ISAM Formats kulcs alatt. Egy lehetséges lista pl. a következő:
  • dBase 5.0
  • dBase III
  • dBase IV
  • Excel 3.0
  • Excel 4.0
  • Excel 5.0
  • Excel 8.0
  • Exchange 4.0
  • HTML Export
  • HTML Import
  • Jet 2.x
  • Jet 3.x
  • Lotus WJ2
  • Lotus WJ3
  • Lotus WK1
  • Lotus WK3
  • Lotus WK4
  • Outlook 9.0
  • Paradox 3.X
  • Paradox 4.X
  • Paradox 5.X
  • Paradox 7.X
  • Text

A példában egy Excel táblához csatlakozunk. A mellékelt xls fájlt másoljuk a c:\ könyvtárba.
Ennek megfelelően a ConnectionString felépítésekor a Kapcsolat ablakban az adatbázis név mezőbe írjuk be: 'c:\teszt1.xls', a Mind ablakban a Data Source property értéke legyen szintén 'c:\teszt1.xls', az Extended Properties értéke pedig 'Excel 8.0'. Végeredményben a ConnectionString így fog kinézni:
"Provider=Microsoft.Jet.OLEDB.4.0;
 Data Source=C:\Teszt1.xls;
 Extended Properties=Excel 8.0;
 Persist Security Info=False"
A táblát a szokásos módon hozzá kell kapcsolni az ADOConnection komponenshez, a DataSource-t a táblához, a gridet a DataSource-hoz. A tábla TableName property-jében az Excel munkafüzet egy lapját kell megadni ('[Munka1$]'). A kapcsolat és a tábla megnyitása után az excel tábla tartalma már látszik is a gridben.

Ha Dbase táblát akarunk megnyitni:
"Provider=Microsoft.Jet.OLEDB.4.0;
 Data Source=C:\DbFiles;
 Extended Properties=dBase 5.0"

Paradox esetén pedig:
"Provider=Microsoft.Jet.OLEDB.4.0;
 Data Source=C:\PxFiles;
 Extended Properties=Paradox 7.X"

A programban példát mutatunk a Properties, Errors, ConnectionObject ADO objektumok használatára is. A 'Connection property-k' gomb megnyomásával kilistázhatjuk a Connection objektum Properties kollekciójának tartalmát, ami más a kapcsolat megnyitása előtt, után és a tábla megnyitása után.
with ADOConnection1.Properties do
  for i := 0 to Count - 1 do
  begin
    try Value := Item[i].Value; except Value := '' end;
    lb1.Items.Add(Item[i].Name + ':' + Value);
end;
Ha az excel tábla megnyitása után megpróbálunk egy értéket módosítani, hibát kapunk. Az OnPostError eseménykezelő megírásával bemutatjuk az Errors property használatát.
  with ADOConnection1.Errors do
  for i := Count - 1 downto 0 do
    with Item[i] do
      ShowMessage(
        ' Description: ' + Description + #13 +
        ' Number: ' + IntToStr(Number) + #13 +
        ' Native: ' + IntToStr(NativeError) + #13 +
        ' Source: ' + Source + #13 +
        ' State: ' + SQLState + #13);
A 'Jet ISAM statisztika' gomb lenyomásával statisztikát kérhetünk a Jet motortól. Ezt az OpenSchema metódus közvetlen megszólításával tesszük, és nem az ADOConnection komponens saját metódusát használjuk.
with ADOConnection1.ConnectionObject.OpenSchema(
      adSchemaProviderSpecific, EmptyParam, 
      JET_SCHEMA_ISAMSTATS) do
  while not EOF do
  begin
    Line := '';
    with Fields do
      for i := 0 to Count - 1 do
        Line := Line + Item[i].Name + ':' +
               IntToStr(Item[i].Value) + #13;
    ShowMessage(Line);
    MoveNext;
end;


TADOConnection

A TADOConnection a BDE TDatabase komponens ADO megfelelője, tehát adatbázis kapcsolat felügyelésére szolgál. Használata nem kötelező. A Command és RecordSet objektumok használhatják ugyanazt a kapcsolatot az adattár eléréséhez, de rendelkezhetnek külön kapcsolattal is. Ha megosztott kapcsolatot szeretnénk használni, akkor van szükségünk a TADOConnection komponensre.

A komponenst arra használhatjuk, hogy kapcsolódjunk egy ADO adattárra. A kapcsolat megadásához a ConnectionString property-ben kell megadnunk a kapcsolódás paramétereit egymástól pontosvesszővel elválasztva. Szerencsére a paraméterezést nem nekünk kell kitalálnunk. Kattintsunk duplán az Object Inspectorban a ConnectionString property-re. Egy dialógusablakot kapunk, amit maga az ADO rendszer prezentál, nem a Delphi. Az ablakban beállíthatjuk a kapcsolat jellemzőit. Mindenképpen kell választanunk egy adatforrás szolgáltatót (provider) és meg kell jelölnünk a szerver és az adatbázis nevét.
Egy példa Connection String-re (A Data Source változó az SQL Servernek otthont adó szerver neve, nálunk éppen NALA.):
ADOConnection1.ConnectionString := 
      'Provider=SQLOLEDB.1;User ID=SA;
      Initial Catalog=pubs;Data Source=NALA';
A ConnectionString szerkesztő ablakban a paraméterek felsorolásán kívül egy fájlnevet is megadhatunk, ha az már tartalmazza a paramétereket. Ez az UDL fájl (Universal Data Link File). Ez valami olyasmi, mint a BDE alias létrehozása, csak az UDL ADO kapcsolatot definiál. Az ADO kapcsolatot tehát kétféleképpen is specifikálhatjuk, UDL fájlban vagy Connection String megadásával. Ha Connection String-et használunk, vagyis a kapcsolatot 'beégetjük' a programba, nyilván újra kell azt fordítanunk, ha a kapcsolat paraméterei megváltoznak. Az UDL fájl használata egyszerűbb, hiszen bármikor átszerkeszthetjük akár Notepad-dal is. (Például, ha az Access adatbázisunk másik meghajtóra kerül, elég az UDL fájlban az UNC hivatkozást átírni.)

Az UDL fájlokat a Windows a Program Files\Common Files\System\OLE DB\Data Links könyvtárban tárolja. Ha jobb egérgombbal kattintunk a fájlra Explorerből, Properties után ugyanazokat a füleket láthatjuk, mint amikor Connection String-et akartunk gyártani a Delphi-ben. UDL fájlt könnyedén előállíthatunk, ha jobb egérgomb után New/Microsoft Data Link-et választunk, majd kettőt kattintunk az új állományon.

Ha nagy szükség van rá, UDL fájlt programból is előállíthatunk. Érdemes belenézni az adodb unitba, a következő eljárásra bukkanhatunk benne:
procedure CreateUDLFile(const FileName, ProviderName, 
    DataSourceName: WideString);
const
  ConnStrTemplate = 'Provider=%s;Data Source=%s'; 
var
  ConnStr: WideString;
  DataInit: IDataInitialize;
begin
  DataInit := CreateComObject(CLSID_DataLinks) as IDataInitialize;
  ConnStr := Format(ConnStrTemplate, [ProviderName, DataSourceName]);
  OleCheck(DataInit.WriteStringToStorage(PWideChar(FileName), 
           PWideChar(ConnStr), CREATE_NEW));
end;
A ConnectionString felépítése után a DataInitialize Ole objektum WriteStringtoStorage metódusának hívásával a string a FileName paraméterben megadott nevű fájlba kerül. A string formája látszólag egyszerű, ahogy az a ConnStrTemplate konstansból is látszik.

Ha a ConnectionString beállításán túl vagyunk, le is ellenőrizhetjük a kapcsolatot a Connection property true-ra állításával. Ekkor az OnWillConnect és az OnConnectComplete eseménykezelők aktiválódnak. A lecsatlakozás a Close metódus hívásával történhet. Ilyenkor először az OnDisconnect eseménykezelő kerül végrehajtásra, majd a kapcsolat leépül.

A komponens állapotát a State property-n keresztül kérdezhetjük le. Ha a kapcsolat inaktív, a State értéke stClosed, ha aktív, stOpen. Az stConnecting érték jelzi, hogy az objektum csatlakozni próbál a megadott adatforráshoz. Amíg ebben az állapotban van, a Cancel metódus hívásával le lehet beszélni a csatlakozásról.

Hogy milyen táblákat és tárolt eljárásokat tartalmaz a kapcsolat másik oldalán az adatbázis, azt a GetTableNames és a GetProcedureNames metódusok adják vissza egy sztringlistában. A TDatabase komponensnél megszokott tranzakció-kezelést itt is megtaláljuk. BeginTrans, CommitTrans és RollbackTrans a metódusok neve, és az InTransaction property mondja meg, hogy van-e nyitott tranzakció, vagy nincs.

Tekintsük át a TADOConnection objektum property-jeit, metódusait és eseményeit.

Property-k:

Attributes: A kapcsolat tranzakciós viselkedését állíthatjuk itt be. A halmaz típusú változónak két eleme lehet, xaCommitRetaining és xaAbortRetaining. Előbbi azt jelenti, hogy egy tranzakciót lezáró commit automatikusan új tranzakciót indít, utóbbi pedig azt, hogy egy tranzakciót lezáró rollback indít automatikusan új tranzakciót.

CommandCount: Csak olvasható tulajdonság, a Connection objektumhoz tartozó összes Command objektumok számát adja meg.

Commands: Csak olvasható tulajdonság, a Connection objektumhoz tartozó összes Command objektumot adja egy listában. Egy elem elérése nagyon egyszerű: ADOConnection1.Commands[i] .

CommandTimeout: A Command objektumban specifikált parancsok végrehajtásának idejét limitálja. Alapértelmezett beállítása 30 másodperc. Ha egy parancs a beállított időn belül nem fut le, végrehajtása megszakad.

Connected: Értéke True, ha a kapcsolat élő, ellenkező esetben False.

ConnectionObject: Ez a property közvetlen hozzáférést biztosít az ADO Connection objektumához. Akkor érdemes használni, ha egy olyan metódusra van szükségünk, amit a TADOConnection komponens nem valósít meg. Igen ritkán van rá szükség. A példaprogramban így érjük el az objektum OpenSchema metódusát.

ConnectionString: A kapcsolat paramétereit tartalmazó string. Az egyes paraméterek vesszővel elválasztva követik egymást. Az ADO négy paramétert értelmez ebben a property-ben, ezek a következők: Provider - a kapcsolat adatszolgáltatóját azonosítja; File name - UDL fájl neve, ha a kapcsolat paraméterei fájlban vannak; Remote Provider - kliens oldali kapcsolat létrehozásakor az adatszolgáltató azonosítója; Remote Server - kliens oldali kapcsolat létrehozásakor a szerver neve. Számtalan további paramétert írhatunk a ConnectionStringbe, de azt már nem az ADO, hanem a Provider fogja értelmezni. Ilyen lehet pl. a felhasználói név és a jelszó. Ha például egy távoli SQL Serverhez akarunk kapcsolódni, a string valami ilyesmi lehet:
"Provider=MS Remote;Remote Server=http://akarmi;
 Remote Provider=MSDASQL;Network Library=DBMSSOCN;
 DSN=Pubs;Uid=sa;Pwd=;" 
Mivel az MSDASQL egy ODBC provider (pontosabban OLE DB for ODBC), a távoli gépen léteznie kell a Pubs nevű DSN-nek. (Szokásos Control Panel/ODBC Data Source/System DSN fül.) A Network Library=DBMSSOCN paraméter utasítja az OLE DB-t, hogy TCP/IP-t használjon az alapértelmezett Named Pipes helyett.

Ugyanez az SQL7 OLE DB providerén:
"Provider=MS Remote;Remote Server=http://akarmi;
Remote Provider=SQLOLEDB;Network Library=DBMSSOCN;
Data Source=valami;Initial Catalog=pubs;User ID=sa;Password=;"

Az Oracle OLE DB provider neve: MSDAORA.

ConnectionTimeout: A kapcsolatfelépítésre szánt időt limitálhatjuk másodpercben.

ConnectOptions: A kapcsolat típusát határozhatjuk meg, értéke coConnectUnspecified, ha szinkron, coAsyncConnect, ha aszinkron a kapcsolat.

CursorLocation: A kurzor helyét lehet beállítani. Ha értéke clUseServer, a kurzor a szerveroldalon jön létre, ha clUseClient, akkor a kliens oldalán.

DataSetCount: A CommandCount-hoz hasonló, csak olvasható tulajdonság. A Connection objektumhoz tartozó összes DataSet objektumok száma.

DataSets: Csak olvasható tulajdonság, a Connection objektumhoz tartozó összes DataSet objektumot adja egy listában. Egy elem elérése nagyon egyszerű: ADOConnection1.DataSets[i] .

DefaultDatabase: Az itt megadott adatbázist a Connection objektum akkor használja, ha a ConnectionString-ben megadott adatbázis nem elérhető, vagy a paraméter nem értelmezhető, hiányzik. Értéke futási időben változik, egy sikeres kapcsolatfelvétel után itt tárolódik a csatlakozott adatbázis.

Errors: Csak olvasható tulajdonság, az Connection objektum Errors kollekciójának reprezentációja. Minden nem ADO-specifikus, provider által generált hiba egy Error objektumként jelenik meg ebben a kollekcióban. Használatára a mellékelt alkalmazásban láthatunk példát.

InTransaction: Boolean változó. Értéke True, ha éppen tranzakcióban vagyunk, egyébként False.

IsolationLevel: A BDE Connection komponenshez hasonlóan az ADO adatbázisokra is specifikálhatunk tranzakció izolációs szintet. A property értéke lehet Read uncommitted, Read committed, Repeatable read és Serializable.

LoginPrompt: Boolean változó, ha True-ra állítjuk, a kapcsolat felépülése előtt megjelenik a bejelentkező ablak (login dialog), hogy rákérdezzen a bejelentkező névre és jelszóra. Mindig a BeforeConnect esemény után és az AfterConnect esemény előtt jelenik meg. Ha OnLogin eseménykezelőt írunk, akkor az jelenik meg helyette. Az OnLogin esemény csak akkor következik be, ha a LoginPrompt értéke True.

Mode: A kapcsolatot jellemző jogosultságokat tartalmazó változó. Értéke lehet cmUnknown, cmRead, cmWrite, cmReadWrite, cmShareDenyRead, cmShareDenyWrite, cmShareExclusive vagy cmShareDenyNone. A cmShareDenyRead azt jelenti, hogy a kapcsolatot más is használhatja, de csak a mi alkalmazásunk írhat rajta keresztül. A cmShareExclusive beállításával csak a mi alkalmazásunk használhatja a kapcsolatot.

Properties: A Connection objektum Properties kollekciójához biztosít közvetlen hozzáférést. Használatára mutatunk példát.

Provider: Az ADO kapcsolat providerét tartalmazza. Értéke a kapcsolat alatt megegyezik a ConnectionString Provider paraméterének értékével.

State: Az ADO kapcsolat pillanatnyi állapotát tartalmazza ez a változó. Értéke lehet stClosed, stOpen, stConnecting, stExecuting és stFetching.

Version: Az aktuális ADO változat verziószámát tartalmazó property.

Metódusok:

BeginTrans: Új tranzakciót indít. Visszatérési értéke (integer) az egymásba ágyazott tranzakciók számát adja vissza. Sikeres tranzakció indításakor az InTransaction property értéke True-ra változik és meghívódik az OnBeginTransComplete eseménykezelő.

Cancel: Egy kapcsolat felvételi kísérletet (Open) szakít meg. Csak aszinkron kapcsolatnál hívható (ConnectOptions = coAsyncConnect).

Close: Lezárja a kapcsolatot. A Connected property értéke False lesz.

CloseDataSets: Lezárja az összes kapcsoló dataset-et anélkül, hogy a kapcsolatot megszüntetné. Paraméterként egy boolean érték adható. Ha True, az összes dataset-et lezárja, ha False, a kliens oldali recordset-ek nyitva maradnak (CursorLocation = clUseClient).

CommitTrans: Sikeresen lezárja a tranzakciót. Meghívja az OnCommitTransComplete eseménykezelőt és az InTransaction property-t False-ra állítja.

Create: A Connection objektum konstruktora.

Destroy: A Connection objektum konstruktora. Lezárja a kapcsolatot, törli és megszünteti a hozzárendelt dataset-ek listáját és megszünteti az interfészt.

Execute: A CommandText paraméterben megadott parancsot hajtja végre. Van függvény és eljárás változata. A függvény visszatérési értéke a parancs által generált recordset.

GetProcedureNames: TStrings-ben visszaadja az adatbázis tárolt eljárásainak nevét.

GetTableNames: TStrings-ben visszaadja az adatbázis tábláinak nevét.

Open: Megnyitja a ConnectionString-ben specifikált adatbázis kapcsolatot. Ha akarjuk, paraméterként megadhatjuk a bejelentkezési nevet és jelszót: Open(UserID, Password);

OpenSchema: Séma-információkat kérhetünk el a kapcsolat provider-étől. Hogy milyen típusú információkra van szükségünk, azt a Schema változóban adjuk meg és meglehetősen sokféle lehet. Az eredmény recordset formában érkezik, amit az eljárás mindenképpen egy TADODataSet-ben akar visszaadni. Ha erre nincs szükségünk, hívhatjuk közvetlenül a Connection objektum OpenSchema objektumát, ahogy ezt a példaalkalmazásban tesszük.

RollbackTrans: Visszagörgeti a tranzakciót. Sikeres végrehajtása esetén meghívódik az OnRollbackTransComplete eseménykezelő és az InTransaction property értéke False-ra áll.

Események:

AfterConnect: A kapcsolat felépülése után hajtódik végre.

AfterDisconnect: A kapcsolat lebontása után hajtódik végre.

BeforeConnect: Az Open metódus hívása után, a kapcsolat felépülése előtt hajtódik végre.

BeforeDisconnect: A Close metódus hívása után, a kapcsolat lebontása előtt hajtódik végre.

OnBeginTransComplete: A BeginTrans metódus lefutása után hajtódik végre. Hiba esetén a vonatkozó információkat az Error változóban adja vissza. Az EventStatus változóban jelzi, hogy az eseményt kiváltó művelet sikeres volt vagy sem (esOK, esErrorsOccured). Minden ADO esemény rendelkezik ezzel a paraméterrel.

OnCommitTransComplete: A CommitTrans metódus lefutása után hajtódik végre.

OnConnectComplete: Sikeres csatlakozás után hajtódik végre.

OnDisconnect: A kapcsolat lebomlása után hajtódik végre.

OnExecuteComplete: Sikeres parancsvégrehajtás (Execute metódus) után kerül meghívásra. A RecordsAffected változóban visszakapjuk a parancs által érintett sorok számát, például egy DELETE hatására hány sor törlődött.

OnInfoMessage: Akkor hajtódik végre, ha a kapcsolat felépülése után információ érkezik a másik oldal felől. Az információkat küldheti például a provider.

OnLogin: A kapcsolat megnyitásakor hívódik meg, ha a LoginPrompt property értéke True.

OnRollbackTransComplete: A RollbackTrans metódus lefutása után hajtódik végre.

OnWillConnect: A kapcsolat létrejötte előtt, a provider pozitív visszajelzése (ok, a kapcsolat felépülhet) után hajtódik végre.

OnWillExecute: Parancs végrehajtása előtt hívódik meg.

ADO paletta cikksorozat