Přehled CDK komponent

TSQL602ODBCConnection

TSQL602Connection

Zjednodušená deklarace třídy:

type TSQL602Connection = class(TComponent);
published
  property ServerName       : string;	
  property UserName         : string;	
  property Password         : string;  
  property LoginPrompt      : Boolean;	
  property Application      : string;	
  property Connected        : Boolean;	
  property DesignServer     : string;	

  property BeforeConnect    : TNotifyEvent;	// události
  property AfterConnect     : TNotifyEvent;	
  property BeforeDisconnect : TNotifyEvent;
  property AfterDisconnect  : TNotifyEvent;
  property BeforeSetApplication : TNotifyEvent;
  property AfterSetApplication  : TNotifyEvent;
  property PasswordExpired      : TPasswExpiredEvent;
  property OnProgress           : TOnProgressEvent;
  property OnEventThreadStart   : TOnEventThreadStart;
  property OnServerDown         : TOnServerDownEvent;
  property OnServerMessage      : TOnServerMessageEvent;
 
public
  property cdp              : cdp_t;   // pouze pro čtení
  property Active           : Boolean; // pouze pro čtení
  property InTransaction    : Boolean; // pouze pro čtení
  property Answered         : Boolean; // pouze pro čtení
  property ServerDown       : Boolean; // pouze pro čtení
  property ClientVersion : TSQL602ClientVersion;  //pouze pro čtení
  property SysCharSet       : Integer;  // pouze pro čtení, od verze 9.5.1 
  
  constructor Create(AOwner : TComponent); override;
  destructor  Destroy; override;
  
  procedure InvokeEvent(Event : TSQL602Event);	
  procedure DispatchEvent(Event : TSQL602Event);
  procedure CopyToFile(FileName : string; Curs : tcurstab; Pos : trecnum; 
            Attr : tattrib; Index : uns16 = NOINDEX);
  procedure CopyFromFile(FileName : string; Curs : tcurstab; Pos : trecnum; 
            Attr : tattrib; Index : uns16 = NOINDEX);
   function Read_BLOB(Curs : tcurstab; Pos : trecnum; Attr : tattrib; 
            Index : uns16 = NOINDEX) : Pointer;
   function Read_BLOB(Curs : tcurstab; Pos : trecnum; Attr : tattrib; 
            Index : uns16; var Len : uns32) : Pointer; overload;
   function GetObjPrivils(SubjName : string; SubjCateg : tcateg; ObjName : string;
            ObjCateg : tcateg; Effective : Boolean) : TSQL602Rights;
  procedure SetObjPrivils(SubjName : string; SubjCateg : tcateg; ObjName : string;
            ObjCateg : tcateg; Rights : TSQL602Rights);
   function ExecuteSQLStatementP(Statement : string; const Args: array of const) : 
            Variant;
   function ExecuteSQLStatementV(Statement : string; const Args: array of const) : 
            Variant;
  procedure ReCreateIndex(TableName : string); 
   function ToLocale(Value : string) : string;          // od verze 9.5.1
   function ToSysCharSet(Value : string) : string;      // od verze 9.5.1
   procedure ProcessNotifications;                      // od verze 10.0  

protected
  procedure DoBeforeConnect; virtual;
  procedure DoAfterConnect; virtual;	
  procedure DoBeforeDisconnect; virtual;
  procedure DoAfterDisconnect; virtual;
  procedure DoOnServerDown; virtual;
  procedure DoSetApplication(Appl : string); virtual;
  function  DoPasswordExpired(User : string; var Pw : string) : Boolean; virtual;  
  procedure DoOnServerMessage(Msg : string); virtual;
end;

Popis

Komponenta reprezentuje jedno klientské připojení na SQL server. Slouží jako kontext spojení s SQL serverem pro ostatní komponenty.

Unit

Vlastnosti komponenty

Jméno zaregistrovaného 602SQL serveru, povinný údaj. Změna vlastnosti nastaví Connected na false.

Příznak zobrazovat přihlašovací dialog. Má-li hodnotu true, zobrazí se při aktivaci spojení s SQL serverem dialog pro zadání uživatelského jména a hesla. Má-li hodnotu false, provede se přihlášení k SQL serveru podle hodnot vlastností UserName a Password. Pokud aplikace potřebuje zobrazovat přihlašovací dialog z Delphi, je nutné ve zdrojovém souboru do sekce uses přidat také unitu DBCtrls nebo DBLogDlg.

Jméno a heslo uživatele databáze, od jména uživatele jsou odvozena přístupová práva k objektům uloženým v databázi. Pokud má vlastnost LoginPrompt hodnotu true, předvyplní se jméno v příslušné složce přihlašovacího dialogu. Pokud má vlastnost LoginPrompt hodnotu false a jméno není zadáno, provede se přihlášení uživatele Anonymous.

Jméno databázové aplikace (schématu) v níž se hledají databázové objekty a v jejímž kontextu se provádí všechny SQL příkazy. Není-li specifikováno, je třeba uvádět jméno aplikace v SQL příkazech explicitně (jako prefix objektu).

Příznak připojení k serveru. Nastavením hodnoty vlastnosti se provede vlastní aktivace nebo deaktivace spojení s SQL serverem. Odpojení od SQL serveru vyvolá deaktivaci všech připojených datasetů a odregistrování sledovaných databázových událostí.

Jméno serveru pro design time. Je-li vlastnost nastavená, tak nezávisle na hodnotě ostatních vlastností (ServerName, UserName, Password, Connected, ...), zaktivuje spojení se specifikovaným SQL serverem a umožní tak během vývoje aplikace získávat od serveru potřebné informace jako seznamy databázových tabulek, seznamy jmen a typů sloupců databázových tabulek seznamy jmen a typů parametrů SQL příkazů a uložených procedur apod. V runtimu se hodnota vlastnosti ignoruje. SQL server musí být zaregistrovaný.

Kontextová proměnná klienta; pouze ke čtení.

Ověřuje aktivitu spojení; vrací (Self <> nil and Connected); pouze ke čtení.

Vrací true, je-li otevřená transakce; pouze ke čtení.

Indikuje připravenost SQL serveru přijmout další požadavek. Má li hodnotu true, je server připraven, má-li hodnotu false, čeká se na dokončení předchozího požadavku a pokus zařadit další požadavek skončí s chybou "Vnoření požadavků na server". Pouze ke čtení. Od verze 8.1.3.12

Nastaví se při prvním výskytu chyby CONNECTION_LOST, shodí se při následujícím požadavku na novou aktivaci spojení. Pouze ke čtení.

Vlastnost slouží ke zjištění verze klientských knihoven 602SQL a k ověření, že všechny knihovny mají stejnou verzi. Jsou-li verze knihoven stejné, vrátí jejich verzi ve čtyřech bajtech struktury TSQL602ClientVersion. Jinak vrátí nulu.

TSQL602ClientVersion = packed record
    case Boolean of
    true:
    (  Build : Byte; Release : Byte; Minor : Byte; Major : Byte; );
    false:
    (  Version : Cardinal; );
end;

Vrací systémový jazyk a kódování serveru. Pouze ke čtení.

Metody komponenty

Komponenta implementuje metody, které zapouzdřují funkce z 602SQL API

Vedle těchto metod jsou na TSQL602Connection implementovány některé další metody:

Metody pro podporu událostí:

Metoda předá SQL serveru požadavek na vyvolání události Event, na kterou pak mohou reagovat ostatní připojení klienti.

Metoda doručí událost Event všem datasetům připojeným k TSQL602Connection tím, že vyvolá příslušné event handlery TSQL602DataSet.OnSQL602Event.

Metody pro podporu práce s atributy proměnné velikosti:

Procedura sloužící pro kopírování obsahu souboru z disku do databáze do sloupce proměnné velikosti (BLOB nebo CLOB)

Procedura sloužící pro vykopírování obsahu sloupce proměnné velikosti z tabulky a uložení do souboru

Funkce načtou hodnotu atributu proměnné velikosti do paměťového bloku alokovaného pomocí funkce GetMem. Tento blok je nutné později uvolnit pomocí FreeMem. Ukazatel na blok se vrací jako hodnota funkce. Je-li potřeba velikost přečteného sloupce proměnné velikosti, druhá varianta funkce ji vrací v parametru Len.

Metody pro zjištění a nastavení objektových práv (nikoliv práv k datům!):

Metoda GetObjPrivils vrací a SetObjPrivils nastavuje práva subjektu k objektu v aktuální aplikaci.

TSQL602Rights = set of TSQL602Right;
TSQL602Right  = (rghtRead, rghtWrite, rghtInsert, rghtDel, rghtGrant, rghtNewRead,
                 rghtNewWrite, rghtNewDel);

Konstanta rghtRead označuje právo použít objekt, konstanta rghtWrite právo editovat objekt, konstanta rghtDel právo zrušit (vymazat z aplikace) objekt, konstanta rghtGrant právo poskytnout tato práva ostatním subjektům. Zbylé konstanty se při nastavování práv k objektům nepoužívají. Právo vytvářet objekty se nastavuje na jiné úrovni (není API).

Umožňuje jedním voláním provést SQL příkaz Statement, který může mít libovolný počet vstupních parametrů a nejvýše jeden výstupní (hlavní význam je pro rychlé SELECT INTO). Vstupní parametry se předávají v poli Args, hodnoty z pole Args se přiřazují jednotlivým parametrům podle pořadí v jakém se parametry vyskytují v SQL příkazu. Výstupní parametr (nebo první z více) se vrací jako hodnota funkce, pokud provedení SQL příkazu skončí s chybou SQ_CARDINALITY_VIOLATION, vrací Null.

var Val : string;
Val := Conn.ExecuteSQLStatementP('SELECT Text INTO :Result FROM Tab WHERE IDi = :Par1 AND IDs = :Par2', [10, 'Test']);

Obdoba ExecuteSQLStatementP s tím, že parametry příkazu, kromě výstupního parametru se specifikují pomocí %konvence jako v případě Delphi funkce Format. Tím je umožněno parametrizovat i ty složky SQL příkazu, které jinak parametrizovat nelze, např. jméno tabulky nebo jméno sloupce.

Val := Conn.ExecuteSQLStatementV('SELECT %s INTO :Result FROM %s WHERE ID = 5', ['MujSloupec', 'MojeTabulka']);

Obnoví (přebuduje) indexy tabulky TableName; je-li jako TableName předán prázdný řetězec, obnoví indexy ve všech tabulkách v aplikaci.

Provede konverzi zadaného řetězce ze systémového kódování připojeného SQL serveru do kódování, které je nastaveno na klientském počítači. Obvykle není potřeba, protože tato konverze se děje automaticky.

Provede konverzi zadaného řetězce z kódování klientského počítače do systémového kódování připojeného SQL serveru. Obvykle není potřeba, protože tato konverze se děje automaticky.

Zajistí doručování notifikačních zpráv od SQL serveru - viz příklad níže.

Pro potřeby potomků jsou určeny metody:

Tyto procedury umožňují v třídě potomka provádět před připojením, po připojení, před odpojením, po odpojení od SQL serveru a při ztrátě spojení potřebné akce.

Umožňuje v třídě potomka provádět při nastavování aplikace další akce.

Umožňuje v třídě potomka reagovat na vypršení hesla.

Umožňuje v třídě potomka reagovat na zprávu zaslanou klientům z řídicího panelu. Od verze 9.

Události komponenty

Rutiny umožňující v aplikaci provádět potřebné akce před připojením, po připojení, před odpojením a po odpojení od SQL serveru. Argumentem Sender je instance třídy TSQL602Connection, která událost vyvolala.

Umožňují v aplikaci provádět před a po nastavení databázové aplikace další potřebné akce. Argumentem Sender je instance třídy TSQL602Connection, která událost vyvolala.

Umožňuje aplikaci ošetřit chybu, kdy se nepodařilo přihlášení uživatele, protože vypršela platnost hesla. Parametrem Sender je objekt třídy TSQL602Connection, na kterém k chybě došlo, parametrem User je jméno uživatele, který se neúspěšně hlásil, parametrem Pw je výstupní proměnná, prostřednictvím které vrátí aplikace nové heslo. Pokud obslužná rutina úspěšně nastaví pomocí metody Set_password nové heslo, vrátí ho prostřednictvím parametru Pw a jako funkční hodnotu vrátí true, bude pokračovat proces aktivace spojení na databázi, jinak bude aktivace přerušena výjimkou.

Umožňuje aplikaci zobrazit informace o postupu operace. K tomu, aby server zasílal informace o postupu, je nutné nastavit ProgressModulus na nenulovou hodnotu. Na platformě Linux není tato událost implementována. Argumentem Sender je instance třídy TSQL602Connection, která událost vyvolala. Num0 a Num1 - indikace postupu, zpravidla počet doposud zpracovaných záznamů a celkový počet záznamů.

Umožňuje aplikaci provést potřebné operace před spuštěním vlákna, které sleduje výskyt databázových událostí, umožňuje určit na účet, kterého uživatele má sledovací vlákno běžet. Pokud procedura vrátí v parametrech User a Pw jméno a heslo, poběží vlákno na účet zadaného uživatele, jinak poběží stejný účet jako hlavní vlákno.

Umožňuje aplikaci provést potřebné operace pokud server skončil nebo se rozpadlo síťové spojení. Následující deaktivační akce tj. odemykání zámků, deaktivace datasetů, SQL příkazů a procedur, ukončování spojení apod. proběhnou v tichosti, jiné požadavky na server vyvolají znovu výjimku s chybou CONNECTION_LOST, ale už bez události OnServerDown.

Umožňuje aplikaci reagovat na příchozí zprávu od jiného klienta (pouze při síťovém spojení). Od verze 9.

procedure TMainForm.SQL602Connection1ServerMessage(Sender: TSQL602Connection; Msg: String);
begin
  ShowMessage('A message from the server '+Sender.ServerName+':'+Chr(10)+Msg);
end;

Má-li se okno se zprávou z předchozího příkladu objevit okamžitě po zaslání zprávy, je třeba ve funkci volané na Application.OnIdle volat metodu ProcessNotifications třídy TSQL602Connection, která zajistí doručování zpráv od serveru.

//po loginu
... 
  Application.OnIdle := MyIdleHandler;
...

procedure TMainForm.MyIdleHandler(Sender: TObject; var Done: Boolean);
begin
  SQL602Connection1.ProcessNotifications;
end;

Příklad

procedure DoNewConnect(srvname : string);
var
  nam,psw : String;
begin
  if LoginDialog(srvname,nam,psw) then begin
    Screen.Cursor := crSQLWait;
    with SQL602Connection1 do begin
      ServerName := srvname;
      LoginPrompt:= FALSE;
      UserName := nam;
      Password := psw;
      Application := '';
      try
        Connected := TRUE;
      except
        on e:ESQL602Exception do HandleBadConnect(e);
      end;
    end;
    if SQL602Connection1.Connected = TRUE then begin
    ...
    end;
  ...  
  end;  
end;  

procedure TMainForm.HandleBadConnect(e: ESQL602Exception);
begin
  Screen.Cursor := crDefault;
  if (e.Error=142) or (e.Error=149) then
     ShowMessage('Chybné přihlašovací údaje!')
  else
     ShowMessage(e.ErrorMessage);
end; 

Seznam subsekcí:

• 602SQL API

Přehled CDK komponent

TSQL602ODBCConnection