602SQL-Úplná dokumentace Index  
<­TSQL602DataSetFind NahoruPřehled CDK komponent TSQL602StoredProc­>

TSQL602Statement

Delphi / Kylix

Zjednodušená deklarace třídy:

type TSQL602Statement = class(TComponent)
published
  property Connection     : TSQL602Connection;	
  property Statement      : string;	
  property Params         : TParams;	
  property DataSet        : TDataSet;
  property Options        : TSQL602SSOptions;
  
  property AfterExecute   : TNotifyEvent;	// událost
   
public
  property StatementCount : Cardinal;
  property AffectedRecCount[i : Integer] : Integer;
  property CursNum[i : Integer]          : tcursnum;
  
  procedure CheckParams; virtual;
  procedure ClearAllParams;
  procedure SetParam(Name : string; Value : Integer; pType : TParamType = ptInput); overload;
  procedure SetParam(Name : string; Value : string; pType : TParamType = ptInput);  overload;
  procedure SetParam(Name : string; Value : string; Size : Integer; pType : TParamType); overload;
  procedure SetParam(Name : string; vType : TFieldType; var Value; Size : Integer; 
            pType : TParamType = ptInput); overload;	
  procedure Execute; virtual;
  function  ParamByName(const ParamName : string) : TParam;
  
end;


Popis

Komponenta slouží k provádění obecného SQL příkazu resp. bloku (max. 10) SQL příkazů. Vlastnost Params umožňuje specifikovat vstupní i výstupní parametry příkazu (umožňuje, propojit SQL příkazy s proměnnými v Delphi). Je-li specifikována vlastnost DataSet, budou se jako hodnoty parametrů (vstupní i výstupní), brát hodnoty stejně pojmenovaných sloupců v aktuálním záznamu. Metodou CheckParams se zanalyzuje SQL příkaz a vytvoří se kolekce parametrů Params automaticky (pouze bez hodnot). Při prvním zavolání metody Execute se SQL příkaz přeloží a připraví a pak je možné ho provádět opakovaně s menší režií serveru, třeba i s různými hodnotami parametrů.
Mezi SQL příkazy lze pro účely této komponenty zařadit i vyhodnocení dotazového výrazu SELECT - provedením vznikne tzv. kurzor (odpověď na SELECT) jedinečného čísla (viz vlastnost CursNum), se kterým je případně možné dále pracovat pouze pomocí 602API funkcí z třídy TSQL602Connection - nelze jej žádným způsobem převézt na dataset či podobnou strukturu. Je nezbytné takovýto kurzor po skončení práce uzavřít pomocí metody TSQL602Connection.Close_cursor.

Unit

SQL602

Vlastnosti komponenty

Connection : TSQL602Connection

Spojení na server pomocí TSQL602Connection. Změna této vlastnosti nebo deaktivace spojení s SQL serverem vyvolá reset komponenty.

Statement : string

Představuje SQL příkaz nebo blok SQL příkazů, který se má provést. Změna této vlastnosti vyvolá reset komponenty. Při zadávání v Design Timu je možné použít vlastní property editor skládající se z okna pro zapsání SQL příkazu a tlačítek Test (aktivní pouze při aktivní konexi, zkontroluje syntaxi příkazu), OK (text z editu se uloží do property) a Storno (zavře okno bez uložení).

Params : TParams

Seznam parametrů SQL příkazu obsahujícího proměnné parametry. Jména, datové typy (ft...) a hodnoty parametrů se specifikují ve vlastnosti Params, např.: 

SQLStm.Statement           := 'SELECT Text INTO :>Val FROM Tabulka WHERE Id= :<Id';
SQLStm.Params[0].Name      := 'Id';
SQLStm.Params[0].ParamType := ptInput;
SQLStm.Params[0].DataType  := ftInteger;
SQLStm.Params[0].Value     := 5;
SQLStm.Params[1].Name      := 'Val';
SQLStm.Params[1].ParamType := ptOutput;
SQLStm.Params[1].DataType  := ftString;
SQLStm.Params[1].Size      := 12;
SQLStm.Execute;
nebo pomocí metod SetParam. Seznam parametrů lze také vytvořit a naplnit (bez hodnot) jednodušeji metodou CheckParams.

Parametry, které odpovídají sloupcům typu CHAR(N) a BINARY(N), musí mít ve vlastnosti Size zadánu délku sloupce. Pokud je délka hodnoty parametru větší než Size, bude při pokusu provést příkaz vyvolána výjimka třídy ESQL602Exception s kódem WBE_PARAMTOOLONG.

DataSet : TDataSet

Hodnoty parametrů mohou být dány hodnotami sloupců v aktuálním záznamu datasetu, který specifikuje vlastnost DataSet, např. mějme dataset DSKlienti, reprezentující tabulku, která má sloupce ID, Jmeno, Prijmeni, TelDom... a dataset DSTel reprezentující tabulku Tel se sloupci IDKlient, Telefon, pak může být SQL příkaz tvořen např. takto: 

SQLStm.Statement := 'SELECT Telefon INTO :>TelDom FROM Tel WHERE IDKlient = :<ID';
SQLStm.DataSet   := DSKlienti;
SQLStm.Params[0].Name      := 'ID';
SQLStm.Params[0].ParamType := ptInput;
SQLStm.Params[0].DataType  := ftInteger;
SQLStm.Params[1].Name      := 'TelDom';
SQLStm.Params[1].ParamType := ptOutput;
SQLStm.Params[1].DataType  := ftInteger;
SQLStm.Execute;
Hodnota parametru se bere z datasetu DataSet, pouze pokud nebyla explicitně nastavena hodnota Value v příslušném parametru, v takovém případě má explicitní hodnota přednost. Po provedení metody Execute je možné se na aktuální hodnoty parametrů pevné velikosti odvolávat prostřednictvím seznamu Params. Číslo telefonu hledané v předchozím příkladu lze získat jednak: 
Telefon := DSKlienti.FieldByName('TelDom').Value;
ale i 
Telefon := SQLStm.Params[1].Value;
Uvedená vlastnost neplatí pro hodnoty proměnné velikosti (BLOB a CLOB), v takovém případě se hodnoty přenášejí pouze z a do datasetu. Na jednotlivé parametry se lze odkazovat pořadovým číslem nebo jménem prostřednictvím metody ParamByName, např.: 
Telefon := SQLStm.ParamByName('TelDom').Value;
Pro nastavení jednotlivých parametrů lze použít také metody SetParam např.: 
SQLStm.SetParam('ID', 5);
SQLStm.SetParam('Val', '', ptOutput);
Je-li ve vlastnosti Options nastaven příznak ssoAutoParams, budou po změně příkazu Statement vyplněny jména, typy a délky parametrů do seznamu Params automaticky. Explicitně lze seznam Params naplnit pomocí metody CheckParams.

Options : TSQL602SSOptions

V současné verzi může být hodnotou vlastnosti Options pouze příznak:
ssoAutoParams Po změně vlastnosti Statement se automaticky zaktualizuje seznam Params a vyplní se jména, typy a délky všech parametrů. Zjištění typů parametrů vyžaduje komunikaci s SQL serverem, při pomalém síťovém spojení může nastavení tohoto příznaku nepatrně zdržovat provedení příkazu.

StatementCount : Cardinal

Po provedení metody Execute vrací počet provedených SQL příkazů (max. 10). V případě provedení (jednoho) příkazu CALL tato hodnota udává počet SQL subpříkazů obsažených v proceduře, tedy může být větší než 1. Pro příkaz CALL nemá proto tato (a dvě následující vlastnosti) velký smysl.

AffectedRecCount[i : Integer] : Integer

Po provedení metody Execute vrací počet záznamů ovlivněných i-tým příkazem (číslováno od nuly).

CursNum[i : Integer] : tcursnum

Po provedení metody Execute vrací číslo kurzoru vytvořeného i-tým příkazem (číslováno od nuly). Takto otevřené kurzory je nezbytné zavírat pomocí metody Close_cursor.



Metody komponenty

procedure SetParam(Name : string; Value : Integer; pType : TParamType = ptInput);

Pro vytvoření parametru odpovídajícímu 602sql typu INT

procedure SetParam(Name : string; Value : string; pType : TParamType = ptInput);

Pro vytvoření vstupního parametru odpovídajícímu 602sql typu CHAR(N)

procedure SetParam(Name : string; Value : string; Size : Integer; pType : TParamType);

Pro vytvoření výstupního parametru odpovídajícímu 602sql typu CHAR(N)

procedure SetParam(Name : string; vType : TFieldType; var Value; Size : Integer; pType : TParamType = ptInput);

Pro ostatní případy. Metody nastavují vlastnosti jednotlivých parametrů:

Name Jméno parametru
Value Hodnota parametru
vType Libovolný typ hodnoty ftFloat, ftMemo, ftBlob aj. v případě, že nemůžete použít jednodušší předchozí varianty.
Size Délka řetězce - povinné pouze u výstupních parametrů pro 602sql typy CHAR(N) nebo BINARY(N), u vstupních parametrů pro 602sql typy proměnné délky (CLOB, BLOB), u výstupních parametrů těchto typů proměné délky není nutné uvádět
pType Typ parametru ptInput pro vstupní parametr, ptOutput pro výstupní parametr nebo ptInputOutput pro INOUT parametr

procedure CheckParams;

Metoda provede analýzu SQL příkazu z vlastnosti Statement a vytvoří a naplní seznam parametrů Params jmény, typy a délkami parametrů. Je třeba poté doplnit pouze vlastnost parametru Value u vstupních parametrů resp. číst u parametrů výstupních.

procedure ClearAllParams;

Nastaví hodnotu všech parametrů ze seznamu Params na nil.

function ParamByName(const ParamName : string) : TParam;

Metoda vrací popis parametru zadaného jména.

procedure Execute; virtual;

Metoda spouští vlastní provedení SQL příkazu. Při prvním zavolání se příkaz přeloží a připraví tak, aby jej bylo možné při dalším použití provést s menší režií serveru.



Události komponenty

procedure AfterExecute(Sender : TObject);

Událost je vyvolána po úspěšném provedení SQL příkazu. Argumentem je komponenta TSQL602Statement, která událost vyvolala.



Příklad

Smazat záznam vyhovující podmínce vytvořené za běhu:

procedure TForm1.ButtonDelClick(Sender: TObject);
// smaže záznam(y)
var
   id : Integer;
begin
  ...
  id := ...;
  SQL602Statement1.SetParam('Id',ftInteger,id,0,ptInput);
//  SQL602Statement1.SetParam('Id',id); - totéž, použita jednodušší varianta metody 
  SQL602Statement1.Statement := 'DELETE FROM TabPokus WHERE ind>=:<Id';
  SQL602Statement1.Execute;
// překreslení datasetu
  SQL602DataSet1.RefreshTo('ind=(SELECT MAX(ind) FROM TabPokus)');
  ...

procedure TForm1.SQL602Statement1AfterExecute(Sender: TObject);
// zobrazí počet smazaných záznamů
var
    mess : String;
begin
    mess := 'Deleted '+ IntToStr(SQL602Statement1.AffectedRecCount[0])+' record(s)';
    MessageBox(0,PChar(mess),'',mb_OK);
end;
<­TSQL602DataSetFind NahoruPřehled CDK komponent TSQL602StoredProc­>