Delphi - A DataSetProvider komponens

DataSetProvider 3. rész

forráskód letöltése
A DataSetProvider komponensről szóló cikksorozat harmadik részében folytatjuk a metódusok ismertetését, valamint rátérünk az események ismertetésére is. A mellékelt példaprogramban egy alkalmazás kiszolgálót készítünk egy kliensalkalmazással. A kiszolgáló egy InterBase adatbázis egyik adatkészletének elérését teszi lehetővé a kliensalkalmazások részére.
A példaprogram kipróbálásához az SQLConnection1 komponens Params property-jében a Database mezőben meg kell adni az adatbázis helyes elérési útvonalát, ha az különbözne a beállítottól.
A kliens alkalmazás futtatása előtt legalább egyszer futtassa a server alkalmazást.
ApplyUpdates
Osztály: TCustomProvider
function ApplyUpdates(
const Delta: OleVariant;
MaxErrors: Integer;
out ErrorCount: Integer
); OleVariant;
Ez az eljárás a delta csomagként megkapott módosításokat aktualizálja az adatkészletben. Az eljárásnak két változata is van:
function ApplyUpdates(const Delta: OleVariant; MaxErrors: Integer; out ErrorCount: Integer); OleVariant; overload;
function ApplyUpdates(const Delta: OleVariant; MaxErrors: Integer; out ErrorCount: Integer; var OwnerData:OleVariant); OleVariant; overload;
Paraméterek
const Delta: OleVariant
Ebben a paraméterben kell megadni a delta csomagot, ami az eredeti és az új adatkészlet közötti különbségeket írja le.
MaxErrors: Integer
Ebben a paraméterben megadhatjuk az engedélyezett hibák számát. Ha a hibák száma átlépné ezt a határértéket, akkor a frissítés megszakad. Ha a paraméter értéke –1, akkor minden módosítást megpróbál véglegesíteni, attól függetlenül, hogy közben hány hiba történt.
out ErrorCount: Integer
Ebben a paraméterben kapjuk meg a művelet közben keletkezett hibák számát.
var OwnerData:OleVariant
Ebben a paraméterben tetszőleges adatokat megadhatunk, amelyeket a BeforeApplyUpdates és az AfterApplyUpdates eseményeknél használhatunk fel. Ha ezek az események módosítottak az adatokon, akkor ebben a paraméterben kapjuk vissza a módosított adatot is. Ha NULL-t adunk meg, akkor az AfterApplyUpdates esemény után nem kapjuk meg az eseményekben esetlegesen használt OwnerData paraméter értékét.
Visszatérési érték
A függvény visszatérési érték egy olyan adatcsomag, amely azokat az adatokat tartalmazza, amelyek aktualizálása nem sikerült.
DataRequest
Osztály: TCustomProvider
function DataRequest(
Input: OleVariant
): OleVariant;
Generál egy OnDataRequest eseményt, és lekérdezi az adatokat.
Paraméterek
Input: OleVariant
Az OnDataRequest eseménynek átadandó paramétert adhatjuk meg itt.
Visszatérési érték
A függvény visszatérési értéke a lekérdezett adatkészlet.
Execute
Osztály: TCustomProvider
procedure Execute(
const CommandText: WideString,
var Params,
OwnerData: OleVariant
);
Ez az eljárás lefuttat egy SQL lekérdezést, vagy tárolt eljárást.
Paraméterek
const CommandText: WideString
A futtatandó SQL lekérdezés, vagy a tárolt eljárás neve. Ez a paraméter figyelmen kívül marad, ha az Options property nem tartalmazza a poAllowCommandText értéket.
var Params
Ebben a paraméterben adhatjuk meg a lekérdezés vagy tárolt eljárás paramétereit, és ebben kapjuk vissza az output paramétereket is.
OwnerData: OleVariant
Ebben a paraméterben tetszőleges adatokat megadhatunk, amelyeket a BeforeExecute és AfterExecute eseményeknél használhatunk fel.
GetParams
Osztály: TCustomProvider
function GetParams(
var OwnerData: OleVariant
); OleVariant;
Ez a függvény lekérdezi az aktuális paraméter értékeket. A paramétereket egy variant tömbben adja vissza, amely szintén variant tömb elemeket tartalmaz. A tömb első dimenziója a paraméter sorszáma. A második dimenzióban négy érték van tárolva, sorrendben: a paraméter neve (string), a paraméter típusa (TFieldType), a paraméter típusa (TParamtype), a paraméter értéke (Variant). Az ilyen módon tárolt paramétereket át tudjuk adni egy TParams típusú objektumnak az UnpackParams globális eljárással.
Paraméterek
var OwnerData: OleVariant
Az OwnerData paraméterben tetszőleges adatokat megadhatunk, amelyeket a BeforeGetParams és AfterGetParams eseményeknél használhatunk fel.
Visszatérési érték
A függvény visszatérési értéke a paraméterlista a fent ismertetett formátumban.
GetRecords
Osztály: TCustomProvider
function GetRecords(
Count: Integer;
out RecsOut: Integer;
Options: Integer
); OleVariant;
Ez a függvény a provider által szolgáltatott adatokat kérdezi le. A függvénynek két változata van:
function GetRecords(Count: Integer; out RecsOut: Integer; Options: Integer); OleVariant; overload;
function GetRecords(Count: Integer; out RecsOut: Integer; Options: Integer; const CommandText: WideString; var Params, OwnerData: OleVariant); OleVariant; overload;
Paraméterek
Count: Integer
Ez a paraméter meghatározza a lekérdezendő rekordok számát. Ha a paraméter értéke -1, akkor az összes rekord szerepelni fog a visszatérési értékben. Ha 0, akkor csak a meta információk szerepelnek majd benne, míg ha nagyobb mint 0, akkor a megadott számú rekordot kérdezi le.
out RecsOut: Integer
Ebben a paraméterben visszakapjuk a lekérdezett rekordok számát.
Options: Integer
Ebben a paraméterben megadhatjuk, hogy milyen adatok kerüljenek bele az adatcsomagba a rekordok adatain kívül. Az értéket konstansok kombinációjával adhatjuk meg. Ezek a konstansok a következők:
Konstans TGetRecordOption Leírás
MetaDataOption grMetaData Az adatcsomag tartalmazni fogja az adatkészlet szerkezetét leíró meta információkat is.
ResetOption grReset A lekérdezés az első rekordtól kezdve történik, függetlenül attól, hogy előtte voltak-e már lekérdezve rekordok.
XMLOption grXML Az adatcsomag XML-ként lesz átadva OleVariant helyett.
XMLUTF8Option grXMLUTF8 Az adatcsomag XML-ként lesz átadva OleVariant helyett, és a kiterjesztett karakterek UTF-8 kódolással lesznek megadva.
const CommandText: WideString;
Ha az Options property tartalmazza a poAllowCommandText értéket, akkor ebben a paraméterben megadhatunk egy SQL lekérdezést, vagy egy tábla illetve tárolt eljárás nevét. Ha ezt megtesszük, akkor ezt fogja használni a provider-hez rendelt adatkészlet helyett.
var Params,
Ebben a paraméterben a CommandText lekérdezés paramétereit adhatjuk meg. Ha az adatkészlet egy TTable, akkor ebben a paraméterben megadhatunk olyan mező értékeket, amikkel szűrjük a lekérdezést.
OwnerData: OleVariant
Ebben a paraméterben saját adatokat adhatunk át, amelyeket a Beforegetrecords és AfterGetRecord eseményekben használhatunk fel. Az AfterGetRecords esemény után a módosított adatokat kapjuk vissza ebben a paraméterben.
Visszatérési érték
A függvény a lekérdezett adatcsomaggal tér vissza.
RowRequest
Osztály: TCustomProvider
function RowRequest(
const Row: OleVariant;
RequestType: Integer;
var OwnerData: OleVariant
): OleVariant;
Az eljárás a megadott rekordról kérdez le információkat.
Paraméterek
const Row: OleVariant
Ennek a paraméternek az értéke alapján dönthetjük el, hogy melyik rekordról kell adatokat lekérdezni.
RequestType: Integer
Ez a paraméter a lekérdezett információ típusát határozza meg. Ez a paraméter egész típusú, de a TFetchOptions felsorolt típus értékeit tartalmazhatja egész formátumban. Ezek az értékek a következők lehetnek:
Érték Jelentés
foRecord A rekord mezőinek értékeit kérdezi le.
foBlobs Az aktuális rekordban található BLOB mezők értékeit kérdezi le.
foDetails Más beágyazott adatkészletek mezőit kérdezi le az aktuális rekordból.
var OwnerData: OleVariant
Visszatérési érték
A TCustomProvider osztályban a függvény visszatérési értéke mindig NULL. A származtatott osztályokban a lekérdezett információkat kapjuk meg delta adatcsomag formátumban.
OnGetDataSetProperties
Osztály: TDataSetProvider
property OnGetDataSetProperties: TGetDSProps;
Amikor a provider hozzáadja az adatkészlet tulajdonságait az adatcsomagokhoz, akkor generál egy OngetDataSetProperties eseményt. Ebben az eseményben további adatokat adhatunk hozzá az adatcsomagokhoz. Ezeket az információkat később a kliens adatkészlet GetOptionalParam függvényével tudjuk lekérdezni az adatcsomagokból.
Az adatokat az esemény Properties paraméterében adhatjuk meg. Ez egy variant tömb, aminek az elemei szintén variant tömbök. Ezek a tömbök három elemet tartalmazhatnak, ezek sorban:
  • egy sztring, ami az elem nevét tartalmazza;
  • egy variant érték, ami az elem értékét tartalmazza;
  • egy logikai érték, ami azt határozza meg, hogy a kliens adatkészlet visszaküldje-e ezt az adatot a delta csomagokkal.
A következő elnevezések foglaltak, ezért nem alkalmazhatók: UNIQUE_KEY, DEFAULT_ORDER, CHANGE_LOG, SERVER_COL, CONSTRAINTS, DATASET_CONTEXT, DATASET_DELTA, LCID, BDERECORD_X, TABLE_NAME, MD_FIELDLINKS, UPDATEMODE.
OnGetTableName
Osztály: TDataSetProvider
property OnGetTableName: TGetTableNameEvent;
Ha az adatkészlet egy TTable komponens, a tábla nevét ki tudja olvasni a TableName property-ből. Ha viszont az adatkészlet egy többtáblás lekérdezés, akkor erre nincs más lehetőség, mint az OnGetableName esemény. Ez az esemény akkor jön létre, amikor a resolver (lásd Resolver property) előkészíti az információkat, hogy melyik táblában kell a frissítéseket végrehajtani. Ezt akkor használhatjuk, amikor a provider nem tudja megállapítani a cél tábla nevét az adatkészletből. Amikor a resolver komponens inicializálása megtörténik, a komponens eltárolja a cél tábla nevét. A tábla neve felhasználható az adatok frissítésére generált SQL utasításokban.

DataSetProvider cikksorozat