TSQLClientDataSet komponens

A mellékelt példához az Interbase példa adatbázisát használjuk. Ha az employee.gdb nem az alapértelmezett helyen található (C:\Program Files\Common Files\Borland Shared\Data\employee.gdb), akkor a program futtatása előtt az SQLConnection1 komponens Params property-jében a Database mező értékét javítsa.

Tehát ez a komponens ugyanazt valósítja meg egyben, amit a ClientDataSet komponens, melyhez egy SQLDataSet komponenst kapcsoltunk egy DataSetProvider komponensen keresztül. Sőt, még az SQLConnection komponenst is elhagyhatjuk, mivel az SQLClientDataSet komponenssel közvetlenül csatlakozhatunk egy adatbázis szerverhez. Ezt a kapcsolatot azonban nem használhatjuk fel a többi komponensnél.

A komponens használata nem ajánlott master-detail kapcsolathoz. Ilyen lekérdezésekhez nem lett optimalizálva, így ez a teljesítményt negatívan befolyásolhatja.

ConnectionName

A property a TSQLConnection osztályban megtalálható azonos nevű property feladatát látja el. Használata csak azért nem ajánlott, mivel az így létrehozott kapcsolatot további komponensek nem tudják használni.

DBConnection

Ebben a property-ben adhatjuk meg azt az SQLConection komponenst, amin keresztül az adatbázishoz kívánunk kapcsolódni.

MasterFields

A master-detail kapcsolatnál a master tábla kulcs mezőinek nevei, pontosvesszővel elválasztva egymástól.

Active

A property-ből megtudható, illetve ezen keresztül beállítható, hogy az adatkészlet meg van-e nyitva, vagy sem. Ha a property értéke hamis, akkor az adatkészlet nincs megnyitva, így semmiféle műveletet nem tudunk végezni az adatokkal.

Amikor a property-nek igaz értéket adunk, akkor a következő események történnek:

Ha a megnyitás közben hiba történt, akkor a State property értéke dsInactive lesz, és a kurzort bezárja.

Ha hamis értéket adunk a property-nek, akkor a következő események történnek:

Options

Ebben a property-ben megadhatjuk, hogy a kliens adatkészlet hogyan kommunikáljon a belső szolgáltatóval (provider).

A következő opciókat állíthatjuk be:

UpdateMode

A property értéke meghatározza, hogy milyen módon keressen rá a rekordra,amikor a módosításokat véglegesíti.

A következő értékei lehetnek:

ActiveAggs

Egy tömb property, amelyből megtudható, hogy mely összesítéseket (Aggregates) támogatja az aktuális index. A tömb indexe a csoportosítás szintjét jelöli (lásd. GroupingLevel). A property egy TList objektumot ad vissza, amelynek elemei az Aggregates property-ben felsorolt összesítések valamelyikére mutatnak. A visszaadott lista természetesen csak az adott index által támogatott, és a megadott csoportosítási szinten elérhető összesítéseket tartalmazza. Ha nincs ilyen, akkor a lista üres, vagy a visszatérési érték nil.

Aggregates

A property egy listát tartalmaz, melynek elemei az adatkészlethez tartozó összesítések (TAggregate). Ennek segítségével különböző összesítéseket, számításokat végeztethetünk el a komponenssel, teljesen automatikusan. Minden összesítés akkor használható csak, amikor a hozzá rendelt index az aktív.

Az TAggregate osztály a következő property-kkel rendelkezik:

Az összesítés eredményét a Value függvénnyel kérdezhetjük le. Ha a GroupingLevel property értéke nem 0, vagyis az összesítés a rekordok egy csoportjára vonatkozik (lásd. GroupingLevel property), akkor annak a csoportnak az összesített eredményét adja meg, amelyikbe az aktuális rekord tartozik.

AggregatesActive

Engedélyezi, vagy éppen letiltja az automatikus összesítéseket. Ha a property értéke hamis (ez az alapértelmezett), akkor az Aggregate property-ben felsorolt összesítések nem fognak működni, tehát az eredményük sem kérdezhető le. Ha a property értéke igaz, akkor mindegyik összesített érték kiszámítódik, amelyek az aktuális indexhez tartoznak. Ha csak egy-egy összesítést szeretnénk letiltani, akkor használjuk az összesítések TAggregate osztályának Active property-jét.

CanModify

A property értékéből megtudható, hogy az adatkészlet szerkeszthető, módosítható-e. Ha a property értéke igaz, akkor a rekordok felvétele, törlése és módosítása lehetséges, ellenkező esetben az adatok csak olvashatóak. Ha a ReadOnly property értéke hamis, akkor a CanModify property értéke igaz.

ChangeCount

A property értéke azt adja meg, hogy hány módosítás történt az adatokon a legutóbbi változtatások tárolása óta. Az adatok végelegesítésekor a property értéke 0-ra változik.

CloneSource

A CloneCursor által megadott adatkészlethez biztosít hozzáférést. Ha nem hívtuk meg a CloneCursor eljárást, akkor a property értéke nil.

Data

Ennek a property-nek az értéke az adatkészlet tartalma bináris formában. Mérete a DataSize property-ből olvasható ki. Ha XML formátumban szeretnénk megkapni az adatkészletet, akkor használjuk az XMLdata property-t.

DataSize

A Data property-ben bináris formában van tárolva az adatkészlet. Ebből a property-ből tudhatjuk meg ennek méretét, bájtban.

Delta

Ezen a property-n keresztül érhető el az az adatcsomag, ami az adatbázison végzett módosításokat tartalmazza. Ez a property szolgáltatja az adatokat az ApplyUpdates és Reconcile metódusokhoz. Ha a módosítások véglegesítésre kerülnek, akkor a property tartalma törlődik. Ha a véglegesítés során hiba lépett fel, akkor a property értéke a következőképpen alakulhat:

XMLData

Ebből a sztring típusú property-ből XML formátumban kiolvashatjuk az adatkészletet.

DataSetField

Annak komponensnek az objektuma (TDataSetField) amely ezt a kliens adatkészletet reprezentálja master-detail kapcsolatban.

Ha a property-nek értéket adunk, akkor a ProviderName, RemoteServer, és FileName property-k értékei törlődnek.

A master adatkészlet természetesen nem lehet ugyanaz, mint a kliens adatkészlet, mivel egy adatkészlet nem ágyazható egybe saját magával.

DataSource

A property egy TCustomClientDataSet objektumra mutat (ha van ilyen), amellyel ez az adatkészlet megosztja az adatait. A property értékét a CloneCursor metódus állítja be. Ha a kliens adatkészlet nem hívta meg ezt a metódust, akkor a property értéke nil.

DisableStringTrim

Ha a property értéke hamis, akkor sztring típusú adatok tárolásakor a felesleges szóközök törölve lesznek a sztring elejéről és végéről. Ha az értéke igaz, akkor a sztring pontosan abban a formában lesz eltárolva a rekordba, ahogyan meg lett adva.

FetchOnDemand

A property értéke meghatározza, hogy az adatok fogadása a szolgáltatótól „szükség szerint” történik-e. Az alapértelmezett értéke igaz, ami azt jelenti, hogy a szolgáltató az összes szükséges adatot elküldi az adatcsomagokban. Ha a szolgáltató nem küldi el automatikusan a BLOB mezők, illetve a detail adatkészlet adatait, akkor állítsuk a property értékét igazra.

Csak abban az esetben állítsuk a property értékét hamisra, ha az alkalmazásunk tartalmaz olyan kódot, ami megoldja az adatcsomagok fogadását a getNextpacker metódus használatával. Ha a property értéke hamis, és a szolgáltató a BLOB mezők adatait nem küldi el automatikusan (az Options property-ben a poFetchBlobsOnDemand opció nincs beállítva), akkor ezeknek az adatoknak a letöltésére a FetchBlobs metódust kell használni. Ha ugyanez a helyzet fennáll a detail adatkészletek esetében is (az Options property-ben a poFetchDetailsOnDemand opció nincs megadva), akkor ezek fogadásához a FetchDetails metódust kell használni.

FileName

Ha az adatok beolvasása és írása egy fájlban történik, akkor a fájl nevét ebben a property-ben kell megadni. Ha a property egy valós fájl nevet tartalmaz, akkor az adatok kiírása automatikusan megtörténik az adatkészlet bezárásakor. Ha a fájl már létezik, akkor az adatkészlet megnyitásakor az adatokat automatikusan beolvassa.

Amikor a komponens elmenti az adatokat a fájlba, akkor ezzel felülírja a fájlban eltárolt adatokat.

Ha az adatokat más-más fájlba szeretnénk menteni, akkor használjuk a SaveToFile metódust, illetve betöltéshez a LoadFromFile metódust az Active property értékének megváltozásakor.

Filter

A property-ben megadhatunk egy szűrő feltételt, ami a megjelenítendő rekordokra vonatkozik. Amelyik rekord megfelel a feltételnek az „látható” lesz az adatkészletben, a több pedig nem. A szűrőt a Filtered property-vel kapcsolhatjuk be, illetve ki. Ha a Filtered property értéke hamis, akkor a szűrő feltétel figyelmen kívül marad.

A Filter-t az adatbázis szerver által támogatott SQL formátumban kell megadni. Ez egyben meghatározza a szűrési lehetőségeket is.

GroupingLevel

A csoportosítási szint maximális értéke. A csoportokat az indexben használt mezők határozzák meg. Az 1-es szintű csoportban azok a rekordok tartoznak ugyanazon csoportba, melyeknél az index első mezőjében azonos érték található. A 2-es csoportba az index első két mezőjében azonos értéket tartalmazó rekordok tartoznak, és így tovább. A 0-s csoport az összes rekordot magában foglalja.

Tegyük fel, hogy egy tábla első mezője egy évszám, a második egy hónap, a harmadik pedig a nap. E szerint a három mező szerint vannak indexelve a rekordok. Ebben az esetben, ha a GroupingLevel=1, akkor a csoportosítás évszám szerint történik, tehát az azonos évszámot tartalmazó rekordok tartoznak egy csoportba. Ha a GroupingLevel=2, akkor már a hónap is számít, tehát egy csoportba az azonos évszámot és hónapot tartalmazó rekordok tartoznak.

Hogy mire jó ez? Például amikor egy táblázatban megjelenítjük a rekordokat, akkor minden rekordról eldönthetjük, hogy az adott szinten lévő csoportban hol foglal helyet (a csoport elején, közepén, vagy végén), így a megjelenítéskor például használhatunk más-más színt az egyes csoportok jelölésére. Az aktuális rekord elhelyezkedését a csoportban a GetGroupState függvénnyel kérdezhetjük le.

IndexDefs

Az adatkészlet indexeinek listáját tartalmazza ez a property, illetve ha új adatkészletet hozunk létre, akkor az ehhez tartozó indexeket tudjuk itt megadni. Egy meglévő táblának nem tudunk itt új indexeket megadni, ehhez használjuk az AddIndex eljárást. A property-n keresztül a következő műveleteket tudjuk elvégezni:

Minden indexhez egy TIndexDef típusú objektum tartozik. Ebben a következő property-ket tudjuk beállítani:

IndexFieldCount

A property megadja, hogy az aktuális indexben hány mező szerepel.

IndexFieldNames

Az aktuálisan használt indexben szereplő mezők neveit tartalmazza, pontosvesszővel elválasztva.

IndexFields

Egy tömb típusú property melynek egyes elemei az indexben szereplő mezők objektumai (TField). Az első mező indexe 0, a másodiké 1, stb. A property értékét ne változtassuk meg közvetlenül, helyette az IndexFieldNames property-t módosítsuk.

IndexName

Az aktuálisan használt index neve. Ha nincs index megadva, akkor az IndexFieldNames property-ben meghatározott sorrendben, vagy az alapértelmezett sorrendben jelennek meg az adatok.

KeyExclusive

A property-vel meghatározhatjuk, hogy a tartomány határaként megadott rekordok szerepeljenek-e a tartományban, vagy nem. Az alapértelmezett értéke hamis, ami azt jelenti, hogy a megadott rekordok szerepelnek a tartományban. Ha a property értéke hamis, akkor a tartomány elejének megadott rekord utáni, és a tartomány végének megadott rekord előtti rekordok jelennek csak meg.

KeyFieldCount

A property értéke meghatározza, hogy a keresésnél (pl. FindKey) hány darab kulcsmező szerepeljen. Alapesetben az értéke a kulcsmezők számával egyezik meg, de lehet ennél kevesebb is. Ha például három kulcsmező van, és a property értéke 2, akkor a keresés csak az első két mező szerint történik, míg egy esetében csak az elsőt veszi figyelembe.

KeySize

A property az elsődleges kulcs méretét adja meg.

LogChanges

Általában amikor módosítunk az adatbázisban tárolt adatokon, a változás nem tárolódik el azonnal, hanem a változtatások a Delta property-ben vannak tárolva. Ebben az esetben ezeket a változtatásokat vissza lehet vonni, vagy éppen véglegesíteni. Ez utóbbi esetben a módosítások végrehajtódnak a Data property-ben tárolt adatokon. Ha a LogChanges property értéke hamis, akkor a módosítások rögtön a data property-ben történnek meg. Ez utóbbit csak akkor használjuk, ha az adatkészlet csak olvasható módban van, mivel egyébként a változtatásokat nem fogjuk tudni véglegesíteni.

MasterSource

Master-detail kapcsolatnál a master tábla DataSource komponense. Miután beállítottuk ennek a property-nek az értékét, meg kell adnunk a MasterFields property-ben azokat a kulcsmezőket, melyekkel létrehozzuk a kapcsolatot.

PacketRecords

A property-vel meghatározhatjuk, hogy egy adatcsomagban egyszerre hány rekord lehet, illetve azt, hogy csak a meta-adatok jöjjenek-e le. Ha a property értéke -1, akkor az összes rekord egyszerre kerül letöltésre. Ha nagyobb mint 0, akkor az az egyszerre letölthető rekordok számát adja meg, ha pedig 0, akkor csak a meta-adatok (adatbázis felépítése) töltődnek le. Az előbbi esetben, tehát amikor a property értéke nagyobb mint 0, az adatok egymás után töltődnek le, az adatbázis szerver meghatározza, hogy pontosan honnan. Ezt a kommunikációt megelőzi a BeforeGetRecords esemény.

Params

A CommandText property-ben megadott SQL lekérdezés vagy tárolt eljárás paramétereit tartalmazó property, amelyben az egyes paraméterek tulajdonságát és értékét állíthatjuk be, illetve tárolt eljárásnál az output paramétereket is ezen keresztül érhetjük el.

ReadOnly

Ha a property értéke igaz, akkor az adatokat nem lehet módosítani. Az alapértelmezett értéke hamis, tehát az adatok módosíthatók. Ha a property értéke igaz, akkor a CanModify property értéke hamis, és fordítva.

RecNo

A property-ből megtudhatjuk az aktuális rekord sorszámát, illetve ha értéket adunk a property-nek, akkor ezzel rápozícionálhatunk a megadott sorszámú rekordra.

RecordCount

A property az adatkészletben található rekordok számát adja meg. Ha a PacketRecords property értéke nagyobb, mint 0, akkor a property értéke változhat, mialatt a provider fogadja az adatokat.

A RecNo property-vel együtt használható az adatkészlet összes rekordjának elérésére, de erre inkább a First és Next függvények használata javasolt.

RecordSize

Annak a buffernek a fizikai mérete bájtban, amibe a rekord adatai beolvasásra kerülnek. Az alkalmazásokban nagyon ritkán van szükség erre az információra, de ha mégis, akkor ebből a property-ből megtudható.

SavePoint

Az adatbázison végzett módosításokat naplózza a komponens. Ebből a property-ből kiolvasható ennek a naplónak a jelenlegi állapota. Ennek segítségével bármikor visszatérhetünk egy korábbi állapotra úgy, hogy eltároljuk a property értékét egy egész típusú változóban, majd ha szükséges, akkor visszaadjuk az értéket a property-nek. Ebben az esetben azok a módosítások, melyek a property értékének eltárolása után történtek, elvesznek. Ha már egyszer visszatértünk egy korábbi állapotba, akkor többször már nem lehet. Ez abban az esetben fordulhat elő, amikor már visszaállítottuk a property értékét egy korábbi értékre, vagy több lépést visszamentünk a RevertRecord metódussal, esetleg töröltük a naplót a CancelUpdates eljárással. Ha egy olyan korábbi állapotot szeretnénk visszaállítani, ami már nem lehetséges, akkor kivételt okozunk.

StatusFilter

A komponens csak az ebben a property-ben megadott állapotú rekordokat teszi elérhetővé. A property a BeforeUpdateRecord esemény felhasználásával együtt hasznos. Egyszerre több érték is beállítható (TUpdateStatus), ezek a következők:

CloneCursor

Egy másik TSQLClientdataSet komponenst ad meg forrásként.

A Source paraméterben kell megadni a másik komponenst. Ha ennek a típusa nem TSQLClientdataSet akkor hibaüzenetet kapunk.

A Reset és a KeepSettnigs logikai típusú paraméterek határozzák meg, hogy a következő property-k értékei hogyan változnak:

Ha mindkét paraméter értéke hamis, akkor a fenti property-k értékei a forrás komponens ugyanezen property-jeinek értékeit veszik fel.

Ha a Reset paraméter értéke igaz, akkor a fent felsorolt property-k értékei törlődnek.

Ha a Reset paraméter értéke hamis, de a KeepSettings paraméteré igaz, akkor a property-k megtartják az eredeti értéküket, de ezeknek kompatibilisnek kell lenniük a forrás adatkészlettel (index-ek).

Az eljárás meghívása után a két adatkészlet meg fog egyezni. Az egyikben végrehajtott módosítások a másikban is végrehajtódnak. Ez olyan szinten igaz, hogy ha például az egyik adatkészletet ReadOnly-ra állítjuk, akkor a másik is az lesz.

GetQuoteChar

A függvény az SQL lekérdezésekben idézőjelként használt karaktert, vagy karaktereket adja vissza. Ezekre akkor lehet szükség, amikor programból generáljuk az SQL script-et a CommandText property-be.

LoadFromFile

A Data property-t egy fájlból tölti fel. Paraméterként megadhatjuk a fájl nevét, de ha ezt nem tesszük meg, vagy csak egy üres sztringet adunk meg, akkor a FileName property értékét veszi figelembe.

A fájl-nak a SaveToFile eljárással elmentett fájlnak kell lennie.

AddIndex

Ezzel az eljárással egy új indexet hozhatunk létre. A Name paraméterben kell megadni az új index nevét, aminek egyedinek kell lennie. A Fields paraméterben kell megadni az indexelt mezőket pontosvesszővel elválasztva. Az Options halmaz típusú paraméterben két TIndexOptions értéket adhatunk meg. Az ixDescendig a csökkenő sorrendet jelenti, míg az ixCaseInsensitive pedig azt adja meg, hogy a kis- és nagybetűk között nincs különbség a rendezésnél. Természetesen a két érték egyszerre is használható. A TIndexOptions típus több értéket is definiál, de ha más értéket is használunk az előbbi kettőn kívül, akkor hibaüzenetet kapunk.

A DescFields paraméter azoknak a mezőknek a neveit tartalmazza pontosvesszővel elválasztva, melyeket csökkenő sorrendben kell rendezni. Ezt a paramétert az ixDescending helyett használjuk akkor, ha az index egyaránt tartalmaz olyan mezőket, melyeket növekvő, és olyanokat, melyeket csökkenő sorrendben kell rendezni. A DescFields paraméterben kell felsorolni a csökkenő sorrendben rendezendő mezőket.

A CaseInsFields az ixCaseInsensitive helyett alkalmazható. Ebben a paraméterben is fel kell sorolni a mezőket pontosvesszővel elválasztva. Azokat a mezőket kell megadni, amelyekben a kis- és nagybetűk közötti különbségek nem számítanak.

A GroupingLevel az alapértelmezett csoportosítási szint, amit az index támogat. A paraméter értéke 0-tól az indexben használt mezők számáig terjedhet (lásd GroupingLevel property).

Az AddIndex eljárással létrehozott index-eket nem lehet elmenteni a SaveToFile eljárással, valamint az adatkészlet bezárásakor is elvesznek. Lezárt adatkészlet esetén nem használható.

AppendData

A provider által szolgáltatott rekordokat átadja az adatkészletnek. A Data paraméterben vannak tárolva a rekordok. A HitEOF paraméter értéke igaz, ha a rekordok beolvasása közben az adatkészlet végére ért.

A legtöbb alkalmazás a GetNextPacket függvényt használja helyette.

ApplyRange

Aktualizálja a SetRangeStart és SetRangeEnd, vagy az EditRangeStart és EditRangeEnd eljárásokkal meghatározott tartományt. Ezután csak a tartományban szereplő rekordok lesznek elérhetők és szerkeszthetők. Az eljárás meghívása után a tartomány első rekordján áll a kurzor.

ApplyUpdates

Véglegesíti a módosításokat az adatbázisban. A MaxErrors property-ben megadhatjuk a véglegesítés közben eltűrt hibák maximális számát. Ha ennél több hiba előfordul, akkor a véglegesítés megszakad. Ha nincs korlátozva a hibák száma, akkor adjunk meg –1-et.

A véglegesítés a következő lépésekben történik:

BookmarkValid

A függvény a paraméterként megadott tábla könyvjelzőről (TBookmark) eldönti, hogy az érvényes-e. Ha a függvény visszatérési értéke igaz, akkor a könyvjelző érvényes, ellenkező esetben nem.

Cancel

Az aktuális rekordon elvégzett, de még nem tárolt (Post) módosításokat törli, és az adatkészlet állapotát (State) dsBrowse-ra állítja. Az eljárást ne tévesszük össze a RevertRecord eljárással, ami az összes fizikailag nem tárolt módosítást törli.

CancelRange

Az eljárás meghívásával megszüntetjük a tartomány kijelölést, így az adatkészlet összes rekordja újra elérhető és szerkeszthető lesz.

CancelUpdates

Az eljárás törli az összes fizikailag még nem tárolt módosítást (rekord felvétel, módosítás, törlés). Ezek a módosítások a Delta property-n keresztül érhetők el, az eljárás ennek tartalmát törli.

CompareBookmarks

Összehasonlít két tábla könyvjelzőt. A két könyvjelzőt a Bookmark1 és Bookmark2 paraméterben kell megadni. A függvény –1-et ad vissza, ha a Bookmark1 kisebb, mint a Bookmark2, 1-et ha nagyobb, és 0-t ha megegyeznek. Egy könyvjelző akkor kisebb egy másiknál, ha a táblában egy kisebb sorszámú rekordra mutat.

ConstraintsDisabled

A függvény visszatérési értéke megmondja, hogy az adatokra vonatkozó megkötések figyelembe lesznek-e véve a módosításkor. Ha a függvény visszatérési értéke igaz, akkor a megkötések nem lesznek figyelembe véve.

CreateBlobStream

Létrehoz egy TClientBlobStream objektumot, melynek segítségével írhatunk és olvashatunk adatokat a Field property-ben megadott BLOB típusú mezőből. A Field property-ben egy TBlobField típusú objektumot kell megadni.

A Mode paraméterben megadhatjuk, hogy milyen műveletet szeretnénk elvégezni a mezővel. Ennek értékei a következők lehetnek:

Ha a FetchOnDemand property értéke igaz, akkor az aktuális rekord adatait beolvassa. Ha hamis, és a provider nem olvassa be automatikusan ezeket az adatokat, akkor a CreateBlobStream függvény előtt meg kell hívni a FetchBlobs eljárást.

CreateDataSet

Létrehoz egy új, üres táblát. A FieldDefs property-ben megadott adatokat figyelembe veszi az új tábla létrehozásakor, illetve ha ez a property üres, akkor a Fields property-t használja fel. Ha mindkét property üres, akkor hibaüzenetet kapunk, tehát legalább az egyiket kötelezően meg kell adni az eljárás meghívása előtt.

Ha az IndexDefs property is tartalmaz adatokat, akkor létrehozza az ebben tárolt indexeket is a táblához, melyeket el is tárol a táblával együtt, amikor megtörténik a mentés.

Az eljárás nemcsak futási időben használható. Ha megadtuk a szükséges adatokat (mező definíciók illetve indexek), akkor kattintsunk a jobb egérgombbal a komponensen, majd válasszuk a Create Dataset menüpontot.

DataRequest

A függvény generál egy OnDataRequest eseményt. A Data paraméter jelentése és a függvény visszatérési értéke nincs előre meghatározva. A Data paraméter az OnDataRequest esemény Input paramétere lesz, míg a függvény visszatérési értéke lehet az esemény visszatérési értéke.

DeleteIndex

Törli a paraméterként megadott nevű indexet. A DEFAULT_ORDER és CHANGEINDEX indexek nem törölhetők.

DisableConstraints

Kikapcsolja az adatokra vonatkozó megkötéseket. Ez néhány esetben a teljesítmény növekedésével jár.

Az eljárás egy számlálót növel. Amíg a számláló értéke nagyobb mint 0, addig a megkötések ki lesznek kapcsolva. Éppen ezért általában párban ajánlatos használni az EnableConstraints eljárással.

EditKey

A kereséshez használt kulcs szerkesztését teszi lehetővé. Az IndexFields property-ben megadott mezőket felhasználva megadhatunk egy új keresési kulcsot. Ez akkor használható ki igazán, amikor több rekordot is keresünk, de a keresési kulcsnak csak egy része különböző az egyes rekordoknál, mivel az EditKey eljárás nem törli az előzőleg megadott kulcsot.

with SQLClientDataSet3 do begin
  EditKey;
  FieldByName(' UPDATER_ID').AsString := ComboBox1.Text;
  GotoKey;
end;

EditRangeEnd

A tartomány végének megadását teszi lehetővé. Meghívása után a FieldByName függvénnyel meghatározhatjuk azt a rekordot, ami a tartomány vége lesz. Ezután az ApplyRange eljárást meghívva aktivizálhatjuk az új tartományt.

EditRangeStart

A tartomány elejének megadását teszi lehetővé. A FieldByName függvénnyel meghatározhatjuk a tartomány elején lévő rekordot. Ezután az EditRangeEnd függvénnyel hasonlóképpen meghatározhatjuk a tartomány végén lévő rekordot, majd az ApplyRange eljárással aktivizálhatjuk a tartományt. Ennek hatására csak a tartományban lévő rekordok lesznek elérhetők.

with SQLClientDataSet2 do begin
  EditRangeStart;
  FieldByName(' EMP_NO').AsInteger := SpinEdit1.Value;
  EditRangeEnd;
  FieldByName(' EMP_NO').AsInteger := SpinEdit2.Value;
  ApplyRange;
end;

EmptyDataSet

Az eljárás az összes rekordot törli a táblából.

EnableConstraints

Engedélyezi a megkötések ellenőrzését. A DisableConstraints által növelt számláló értékét csökkenti. Ha a számláló értéke 0, akkor a megkötések ellenőrzése megtörténik, ellenkező esetben nem. Ebből következik, hogy az EnableConstraints eljárást legalább annyiszor meg kell hívni, mint előtte a DisableConstraints eljárást.

Execute

Az eljárás olyan SQL parancsok és tárolt eljárások futtatását teszi lehetővé, melyeknek nincs visszatérési értékük (pl. egy adatkészlet). A futtatás után az esetleges output paraméterek értékei a Params property-ből olvashatók ki (pl. a ParamByName függvénnyel).

Az eljárás futtatásakor először létrejön egy BeforeExecution esemény. Ezután fut le a lekérdezés vagy tárolt eljárás, és miután a Params property frissítése is megtörtént, generál egy AfterExecute eseményt.

Az eljárás nem használható olyan lekérdezések és tárolt eljárások futtatására, melyek egy kurzort adnak vissza.

FetchBlobs

A BLOB típusú adatok lekérdezését hajtja végre ez az eljárás, amennyiben az nem történik meg automatikusan (pl. amikor az Options property-ben a poFetchBlobsOnDemand opció meg van adva).

Az eljárás meghívására nincs szükség, ha a provider automatikusan letölti ezeket az adatokat is, illetve a poFetchBlobsOnDemand opció nincs bekapcsolva.

FetchDetails

Frissíti a detail adatkészletet, ha ez egyébként nem történik meg automatikusan. Ez utóbbi eset akkor következhet be, ha az Options property-ben a poFetchDetailsOnDemand opció meg van adva.

Az eljárás használatára nincs szükség, ha a detail adatkészlet automatikusan megtörténik, vagy a FetchOnDemand property értéke igaz.

FetchParams

Frissíti a Params property-ben tárolt paraméterek értékeit. Természetesen csak akkor van hatása, ha az adatkészlet rendelkezik paraméterekkel.

Az eljárást szerkesztési időben is futtathatjuk, ha a komponens menüjéből kiválasztjuk a Fetch Params menüpontot.

FindKey

Az aktuális index szerinti keresést tesz lehetővé. Paraméterként megadható az indexben szereplő mezőkhöz egy-egy érték, ami lehet sztring, szám, NULL vagy nil. Ha a megadott értékek száma kevesebb, mint az index-ben szereplő mezőké, akkor a hiányzó mezőkhöz tartozó értékek NULL értékként lesznek figyelembe véve.

Ha a keresés eredmény sikeres, akkor a kurzort a megtalált rekordra állítja, és a függvény visszatérési értéke igaz lesz. Ellenkező esetben a kurzor nem mozdul, és a visszatérési érték hamis.

if SQLClientDataSet1.FindKey([20, ’Alma’]) then ...

FindNearest

Az eljárást keresésre használhatjuk, hasonlóan a FindKey függvényhez. A különbség csak annyi, hogy itt a megadott értékeknek nem kell feltétlenül teljesen megegyezniük a rekordokban tárolt adatokkal. Az eljárás rápozícionál arra a rekordra, amelyre leginkább illeszkedik a megadott érték, vagy az első rekordra, amely a megadott értéknél nagyobb. Ha egyik sem lehetséges, akkor az utolsó rekordra állítja a kurzort. Az eljárás csak sztring típusú adatok esetén használható.

GetCurrentRecord

Beolvassa az aktuális rekordot a Buffer paraméter (PChar) által megadott bufferba. A buffer méretének legalább akkorának kell lennie, mint a RecordSize property értékének. A legtöbb alkalmazásnál nem kell használni ezt a függvényt, mivel a rekord beolvasása automatikusan megtörténik.

GetGroupState

Egy halmaz típusú (TGroupPosInds) property, amelyben megkapjuk, hogy az aktuális rekord a Level paraméterben megadott szintű csoportban hogyan helyezkedik el. A Level paraméter azonosítja a csoportot, a csoport szintjével. Ha ez az érték 1, akkor ez megfelel az index első mezőjének, ha kettő, akkor az első kettő mezőnek, és így tovább. Ha a paraméter értéke nagyobb, mint a GroupingLevel property értéke, akkor hibaüzenetet kapunk.

A függvény visszatérési értéke TGroupPosInds típusú, melyben az alábbi értékeket kaphatjuk meg:

GetIndexInfo

Beolvassa az információkat az aktuális indexről. Feltölti az adatkészlet belső index mezőit az aktuális index adataival. Ha a csoportosítási szintet is be kell olvasni, akkor az IndexName paraméterben meg kell adni az index nevét, mivel e nélkül ez az információ nem lesz beolvasva. Az IndexName paraméterben nem adható meg más index neve, csak az aktuális indexé.

GetIndexNames

A paraméterként megadott TStrings típusú objektumot feltölti az indexek neveivel. A DEFAULT_ORDER (a rekordok alapértelmezett sorrendje), és a CHANGEINDEX (a módosított rekordokat tartalmazza) indexek minden adatkészlethez automatikusan létrejönnek.

SQLClientDataSet1.GetIndexNames(ComboBox1.Items);

GetNextPacket

Lekérdezi a rekordok következő csoportját. Az egy csoportban lévő rekordok számát a PacketRecords property adja meg. Az újonnan beolvasott csomagban található rekordok hozzáadódnak a Data property-be már előzőleg beolvasott rekordokhoz.

A függvény visszatérési értéke a beolvasott rekordok száma. Ha ez az érték 0, akkor már az összes rekord be lett olvasva.

GetOptionalParam

A provider az adatcsomagokhoz extra kiegészítő adatokat is csatolhat. Ezzel a függvénnyel ezeket kérdezhetjük le. Paraméterként az adat nevét kell megadni.

GotoCurrent

Két azonos adatkészlet esetén használható, ha azt szeretnénk, hogy mindkét adatkészletben ugyanaz legyen az aktuális rekord. A paraméterként megadott adatkészlet aktuális rekordjának megfelelő rekordra helyezi a kurzort.

GotoKey

Az EditKey vagy SetKey után megadott kulcsú rekordra ugrik. Ha nem talált ilyen rekordot, akkor a függvény visszatérési értéke hamis, és a kurzor nem változik, ellenkező esetben a visszatérési érték igaz, és a megtalált rekordra helyezi a kurzort.

GotoNearest

Annyiban különbözik a GotoKey függvénytől, hogy itt a megadott kulcsnak nem kell pontosan megegyezni a rekordban tárolt adatokkal. Arra a rekordra pozícionál, amelynek adataira a legjobban illeszkedik a megadott kulcs, vagy ha nincs ilyen rekord, akkor az első rekordra ugrik, amelyik a kulcsnál nagyobb. Ha ilyen sincs, akkor az utolsó rekordra ugrik.

LoadFromStream

A megadott TStream típusú objektumból tölti fel a Data property-t, amiben az adatkészletet tárolja. Az adatfolyam formátumának meg kell egyeznie a kliens adatkészlet belső formátumával. Például megadható egy olyan TStream objektum, amiben előzőleg a SaveToStream eljárással feltöltöttük az adatokat, akár egy másik adatkészletből.

Locate

A kulcstól független keresést tesz lehetővé. A KeyFields paraméterben meg kell adni azokat a mezőket, amelyekben keresni akarunk. A mezők neveit pontosvesszővel kell elválasztani egymástól. A KeyValues paraméterben a keresett adatot, vagy adatokat kell megadni. Ha több mezőben is keresünk, akkor használjuk a VarArrayOf függvényt az adatok megadására, ahogy az a lenti példában is látszik. Az Options paraméterben megadhatók a kereséssel kapcsolatos opciók, amiket csak sztring típusú mezők esetén vesz figyelembe. Ez egy TLocateOptions típusú halmaz paraméter, melyben a következő két értéket adhatjuk meg:

Ha a függvény megtalálta a keresett rekordot, akkor a visszatérési értéke igaz, és rá is pozícionál a rekordra. Ellenkező esetben a visszatérési érték hamis, és a kurzor nem mozdul.

if SQLClientDataSet1.Locate(’Tipus;Nev’, VarArrayof([10, Edit1.Text]), [loCaseInsensitive, loPartialKey]) then ...

Lookup

A függvény megkeresi a megadott kulccsal rendelkező rekordot, és a szintén megadott mezők értékeivel tér vissza. A KeyFields paraméterben kell pontosvesszővel elválasztva megadni azokat a mezőket, amelyekben keresni szeretnénk. A KeyValues paraméterben a keresett értékeket tudjuk megadni, ugyanúgy, mint a Locate függvénynél. A harmadik paraméter a ResultFields, amelyben azokat a mezőket kell megadni, amelyekben tárolt adatokra szükségünk van. A mezőneveket itt is pontosvesszővel kell egymástól elválasztani.

A függvény visszatérési értéke egy tömb, amelynek Variant típusú elemei a ResultFields paraméterben megadott mezők adatait tartalmazzák.

MergeChangeLog

A naplózott módosításokat végrehajtja az adatokon.

Reconcile

Törli a véglegesített módosításokat. Általában az ApplyUpdates függvény hívja meg automatikusan, miután a módosításokat véglegesítette. A Results paraméter egy Variant típusú érték, ami tartalmazza azokat a rekordokat, amelyeket valamilyen hiba folytán nem sikerült véglegesíteni, illetve a hibára vonatkozó információkat is. A függvény generál minden hibás rekordnál egy OnReconcileError eseményt. A Delta property a függvényhívás után csak azokat a rekordokat fogja tartalmazni, melyeket nem sikerült véglegesíteni, méghozzá az OnReconcileError eseményben módosított adatokkal.

Ha a véglegesítés során nem volt hibás rekord, akkor a függvény visszatérési értéke igaz, ellenkező esetben hamis.

RefreshRecord

Az eljárás az aktuális rekord adatait újra lekérdezi az adatbázis szerverről. Ez azt jelenti, hogy a rekordban elvégzett, de még nem véglegesített módosítások is elvesznek.

RevertRecord

Törli az aktuális rekord összes eddig elvégzett módosítását, amik még nem lettek véglegesítve.

SaveToFile

Elmenti az adatkészletet a paraméterként megadott fájlba. Ha a FileName paraméter egy üres sztring, akkor a FileName property-ben megadott fájlba menti az adatokat. Ha a fájl már létezett, akkor azt felülírja.

A Format paraméterben megadhatjuk a fájl formátumát. Ezek a következők lehetnek:

SaveToStream

Az adatkészletet elmenti egy adatfolyamba (TStream). Itt is megadható a formátum, ugyanazok az értékek használhatók, mint a SaveToFile eljárásnál. A DataSize property-ből megtudható, hogy mekkora bufferre van szükség a mentéshez.

SetAltRecBuffers

Normális esetben ennek az eljárásnak a használatára nincs szükség. Az Old, New és Cur paraméterekben megadhatjuk azoknak a buffereknek a pointereit, amelyeken keresztül Field komponens OldValue, NewValue és CurValue property-jeihez férhetünk hozzá.

SetKey

A SetKey eljárás annyiban különbözik az EditKey-től, hogy ez az előzőleg definiált keresési kulcsot törli.

SetOptionalParam

Az eljárással saját adatokat fűzhetünk hozzá az adatcsomaghoz. Ezek az adatok mentésre kerülnek a data property tartalmával együtt, amikor fájlba, vagy egy stream-be (TStream) másoljuk azt. Az ilyen módon megadott adatokat a GetOptionalParam függvénnyel kérdezhetjük le.

A ParamName paraméterben megadhatjuk az információ nevét, amivel az eltárolt adatokat azonosítani szeretnénk. Ez egy tetszőleges sztring lehet, ezek kivételével: UNIQUE_KEY, DEFAULT_ORDER, CHANGE_LOG, SERVER_COL, CONSTRAINTS, DATASET_CONTEXT, DATASET_DELTA, LCID, BDERECORD_X, TABLE_NAME, MD_FIELDLINKS, UPDATEMODE.

A Value paraméter OleVariant típusú, ez tartalmazza azokat az adatokat, amelyeket az adatcsomaghoz szeretnénk kapcsolni.

Ha az IncludeInDelta paraméter értéke igaz (alapértelmezetten hamis), akkor az adatok a Delta property-ben is eltárolódnak, ami azt jelenti, hogy az adatok véglegesítésekor ezek is el lesznek küldve a provider-nek. Ekkor az OnUpdateData eseményben lekérdezhetjük ezeket az adatokat a GetOptionalParam függvénnyel.

SetRange

A tartomány elejét és végét adhatjuk meg egy lépésben a StartValues és EndValues paraméterekkel. Mindkét paraméter tömb típusú, így annyi értéket adhatunk meg bennük, amennyi mezőből az aktuális index áll. Ha ennél kevesebbet adunk meg, akkor a meg nem adott értékeknél NULL-t vesz figyelembe.

Az eljárással egy lépésben megoldhatjuk azt, amit a SetRangeStart, SetRangeEnd, és ApplyRange eljárásokkal tudunk egyébként megtenni.

SQLClientDataSet1.SetRange([10, ’A’], [20, ’J’]);

SetRangeEnd

Az adatkészletet dsSetKey állapotba állítja. Ezután a FieldByName függvénnyel megadhatjuk azt a rekordot, amely a tartomány utolsó rekordja lesz. A tartomány aktualizálása az ApplyRange eljárással történhet meg.

with SQLClientDataSet1 do begin
  SetRangeStart; FieldByName(’Sorszam’).AsInteger:=10;
  SetRangeEnd; FieldByName(’Sorszam’).AsInteger:=99; ApplyRange;
end;

SetRangeStart

Az adatkészletet dsSetKey állapotba állítja. Ekkor megadhatjuk a FieldByName függvénnyel azt a rekordot, amely a tartomány első rekordja lesz. A tartomány aktualizálása az ApplyRange eljárással történhet. Előtte azonban általában van még egy SetRangeEnd eljárás, ami után a tartomány végét jelentő rekordot adhatjuk meg.

UndoLastChange

Érvényteleníti az utolsó módosítást, rekordbeszúrást, vagy törlést. Ha a FollowChange paraméter értéke igaz, akkor arra a rekordra pozícionál, amellyel az utolsó módosítás történt (amely módosítást érvénytelenítettük), ha hamis, akkor az aktuális rekordon marad a kurzor.

UpdateStatus

Megadja az aktuális rekord állapotát. Az állapot a szerkesztés, beszúrás és törlés műveletekkel változik. A következő értékei lehetnek:

AfterUpdateRecord

Az esemény a rekord adatainak tárolása után jön létre. A SourceDS paraméterben megkapjuk a forrás adatkészlet objektumát (TDataSet). Ha nincs ilyen, akkor a paraméter értéke nil. Ha hozzá akarunk férni ebben az adatkészletben lévő rekordokhoz, akkor győződjünk meg róla, hogy az adatkészlet meg van e- nyitva (Active property), mivel ez nem biztos. A DeltaDS paraméter annak a kliens adatkészletnek az objektuma, amely az éppen rekordot frissítendő rekordot tartalmazza. Az UpdateKind paraméterből megtudhatjuk, hogy pontosan miért is kell frissíteni a rekordot, vagyis milyen művelet történik vele. Értékei a következők lehetnek:

BeforeUpdateRecord

A rekordok módosításainak véglegesítése előtt jön létre ez az esemény. A SourceDS paraméterben megkapjuk annak az adatkészletnek az objektumát (TDataSet), ahonnan az adatok eredetileg származnak. A DeltaDS az az adatkészlet, amiben a módosított, és most véglegesítendő adatok vannak. Az aktuális rekord ebben az adatkészletben az, amelynek a véglegesítése megtörténik.

Az UpdateKind paraméterből megtudhatjuk, hogy az éppen véglegesítendő rekord új rekord-e (ukInsert), módosított (ukModify), vagy törölt (ukDelete).

Ha az Applied paraméternek igaz értéket adunk, akkor a rekord véglegesítése nem történik meg.

OnGetTableName

Az esemény akkor jön létre, amikor a provider-nek szüksége van annak a táblának a nevére, amelyben az adatokat véglegesíteni kell. Ha az adatkészlet egy több táblás lekérdezés, akkor a provider nem tudja a tábla nevét megállapítani. A TableName paraméterben adhatjuk meg a tábla nevét, amit a frissítést végző SQL parancsnál fog felhasználni.

OnUpdateData

Az esemény közvetlenül az adatok véglegesítése előtt következik be. Ezt az eseményt felhasználhatjuk az adatok ellenőrzésére, vagy éppen titkosítására. A DataSet property-ben megkapjuk azokat a rekordokat, amelyek véglegesítésre kerülnek.

OnUpdateError

Akkor jön létre, amikor egy rekord véglegesítése közben hiba történt. A DataSet paraméterben egy átmeneti adatkészlet objektumát kapjuk meg, amin keresztül ellenőrizhetjük a field komponensek NewValue, OldValue és CurValue property-jeinek értékeit, hogy vajon mi okozhatta a hibát. Nagyon fontos, hogy olyan műveletet ne végezzünk, aminek hatására az aktuális rekordról átlépünk egy másik rekordra. Az E paraméter egy EUpdateError típusú objektum, amiből pontosan megtudhatjuk a hibaüzenetet, valamint annak okát. Az UpdateKind paraméterből megtudhatjuk, hogy milyen művelet volt az, ami a hibát okozta. Ez a paraméter megegyezik a BeforeUpdateRecord esemény ugyanezen paraméterével. A Response paraméterben megadhatjuk, hogy mi történjen azután, hogy befejeződik az eseménykezelő eljárás. Az alapértelmezett értéke az ApplyUpdates eljárás MaxErrors paraméterének értékétől függ. Ha ez 0, akkor rrAbort, egyébként rrSkip. Ha az eseménykezelő eljárásban kijavítottuk a hibát, akkor a Response paraméter értékét állítsuk rrApply-ra.

AfterApplyUpdates

Az esemény az adatok véglegesítése után jön létre, de még a Reconcile függvény meghívása előtt (nem ugyanaz, mint a BeforeApplyUpdates esemény!). Az ApplyUpdates eljárásnál részletesen ismertetve van, hogy milyen események történnek az eljárás meghívása után.

AfterExecute

Az Execute metódus meghívása után jön létre ez az esemény. Az Execute eljárásnál részletesen ismertetve van, hogy milyen események történnek az eljárás meghívása után.

AfterGetParams

Az esemény azután következik be, miután az adatkészlet megkapta a paramétereket a provider-től.

AfterGetRecords

Az esemény azután jön létre, miután az adatkészlet egy adatcsomagot kapott a provider-től.

AfterRowRequest

Az esemény azután következik be, miután az adatkészlet új információkat kapott az aktuális rekordról.

BeforeApplyUpdates

Az esemény azelőtt következik be, mielőtt az adatok véglegesítésre kerülnek a szerveren.

BeforeExecute

Az esemény még azelőtt jön létre, mielőtt az adatkészlet futtatná a lekérdezést vagy tárolt eljárást.

BeforeGetParams

Az esemény azelőtt következik be, mielőtt az adatkészlet fogadná a provider-től a paramétereket.

BeforeGetRecords

Az esemény közvetlenül a következő adatcsomag (rekordok) letöltése előtt jön létre.

BeforeRowRequest

Azelőtt jön létre, mielőtt az adatkészlet új információkat fogadna az aktuális rekordról.

OnReconcileError

Akkor jön létre ez az esemény, amikor szükséges a nem véglegesített adatok egyeztetése. Ez az esemény csak azokat a hibákat kezeli, amelyek nem lettek megoldva az OnUpdateError eseményben.

Az esemény minden egyes rekordnál külön meghívásra kerül, amely rekordoknál hiba lépett fel a véglegesítéskor.

A DataSet paraméterben megkapjuk azt az adatkészletet, amely a hibát generálta. Master-detail kapcsolatnál, ha a hiba a detail adatkészletnél történt, akkor ezt az adatkészletet érhetjük el a paraméteren keresztül, még akkor is, ha a master adatkészlet OnReconcileError eseménye következett be. A paraméterként megkapott adatkészletnél ne végezzünk olyan műveleteket, amely a kurzor elmozdulását vonja maga után (pl. Next metódus). A field komponensek NewValue, OldValue és CurValue property-jeinek értékeiből kideríthetjük, hogy vajon mi okozhatta a hibát. Az E paraméter egy EReconcileError objektumra mutat, amelyben a pontos hibaüzenet, és a hiba oka található. Ezt az információt használhatjuk fel arra, hogy hogyan válaszoljunk a hibára.