Obsah
Rejstřík 🔎︎

# Služba SFDatabases.Database

Služba Database poskytuje přístup k databázím, a to jak vestavěným, tak popsaným v dokumentech Base. Pomocí metod této služby lze:

- Přistupovat k datům v databázových tabulkách.

- Spouštět dotazy SELECT a používat agregační funkce.

- Spouštět SQL příkazy jako INSERT, UPDATE, DELETE atd.

Každá instance služby Database se vztahuje k jediné databázi a nabízí přístup k jejím tabulkám, dotazům a datům.

Služba nenabízí přístup k formulářům a sestavám v dokumentu Base, který obsahuje databázi. Pro přístup k formulářům použijte metodu FormDocuments služby Base.

Služba a databáze spolu komunikují pouze prostřednictvím SQL.

SQL příkazy je možné spouštět v přímém nebo nepřímém režimu. V přímém režimu se příkaz předává databázovému enginu bez jakékoliv kontroly syntaxe.

Poskytnutá rozhraní zahrnují jednoduché seznamy tabulek a dotazů a přístup k datům databáze.

Chcete-li mít SQL příkazy čitelnější, můžete názvy tabulek, dotazů a polí uzavřít do hranatých závorek "[]" místo do jiných znaků, které mohou být specifické pro určité RDBMS (Relational Database Management System). Mějte však na paměti, že v tom případě jsou tyto uzavírající závorky povinné.

## Volání služby

### Syntaxe:

Instanci služby Database můžete vytvořit pomocí metody CreateScriptService:

CreateScriptService("SFDatabases.Database", [filename: str], [registrationname], [readonly], [user, [password]]): svc

Jako první argument metody CreateScriptService můžete použít buď "SFDatabases.Database", nebo jednodušší "Database".

### Parametry:

filename: Název souboru aplikace Base. Musí odpovídat zápisu SF_FileSystem.FileNaming.

registrationname: Název zaregistrované databáze. Používá-li se filename, neměl by být tento argument uveden.

Platí to i naopak: pokud je uveden argument registrationname, argument filename by již neměl být zadán.

readonly: Určuje, zda bude databáze otevřena pouze pro čtení (výchozí = True).

user, password: Další parametry spojení s databázovým serverem.

### Příklad:

##### V Basicu

          GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
          Dim myDatabase as Object
          Set myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
          ' Spouštění dotazů, SQL příkazů, ...
          myDatabase.CloseDatabase()

##### V Pythonu

          from scriptforge import CreateScriptService
          myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
          # Spouštění dotazů, SQL příkazů, ...
          myDatabase.CloseDatabase()

## Přístup k databázím pomocí služby UI

K databázi přiřazené k dokumentu Base je možné přistupovat také pomocí služby ScriptForge.UI, jak ukazují následující příklady:

##### V Basicu

          Dim myDoc As Object, myDatabase As Object, ui As Object
          Set ui = CreateScriptService("UI")
          Set myDoc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
          ' Níže jsou uvedeny uživatel a heslo, jsou-li potřeba
          Set myDatabase = myDoc.GetDatabase()
          ' Spouštění dotazů, SQL příkazů, ...
          myDatabase.CloseDatabase()
          myDoc.CloseDocument()

##### V Pythonu

          ui = CreateScriptService("UI")
          doc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
          # Níže jsou uvedeny uživatel a heslo, jsou-li potřeba
          myDatabase = doc.GetDatabase()
          # Spouštění dotazů, SQL příkazů, ...
          myDatabase.CloseDatabase()
          doc.CloseDocument()

Metoda GetDatabase z výše uvedeného příkladu je součástí služby ScriptForge Base.

## Vlastnosti

Název | Pouze pro čtení | Typ | Popis
Queries | ano | pole řetězců (String) | Seznam uložených dotazů.
Tables | ano | pole řetězců (String) | Seznam uložených tabulek.
XConnection | ano | XConnection | Objekt UNO představující aktuální spojení s databází.
XMetaData | ano | XDatabaseMetaData | Objekt UNO představující metadata popisující atributy databázového systému.

Seznam metod služby Database
CloseDatabase DAvg DCount | DMin DMax DSum | DLookup GetRows RunSql

## CloseDatabase

Zavře aktuální spojení s databází.

### Syntaxe:

db.CloseDatabase()

### Příklad:

        myDatabase.CloseDatabase() ' Basic

        myDatabase.CloseDatabase() # Python

## DAvg, DCount, DMin, DMax, DSum

Vypočítá zadanou agregační funkci pro pole nebo výraz příslušející k tabulce.

Volitelně lze zadat SQL klauzuli WHERE, která před agregační funkcí použije na data filtr .

### Syntaxe:

db.DAvg(expression: str, tablename: str, [criteria: str]): any

db.DCount(expression: str, tablename: str, [criteria: str]): any

db.DMin(expression: str, tablename: str, [criteria: str]): any

db.DMax(expression: str, tablename: str, [criteria: str]): any

db.DSum(expression: str, tablename: str, [criteria: str]): any

### Parametry:

expression: SQL příkaz s názvy polí uzavřenými v hranatých závorkách.

tablename: Název tabulky (bez hranatých závorek).

criteria: Klauzule WHERE bez klíčového slova "WHERE", názvy polí jsou uzavřeny v hranatých závorkách.

### Příklad:

V následujícím příkladu se předpokládá existence souboru Employees.odb obsahujícího tabulku EmployeeData.

##### V Basicu

          GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
          Dim myDB as Variant
          Set myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")
          ' Zjistí počet zaměstnanců v tabulce
          MsgBox myDB.DCount("[ID]", "EmployeeData")
          ' Vrátí součet všech platů v tabulce
          MsgBox myDB.DSum("[Salary]", "EmployeeData")
          ' Níže jsou uvedeny příklady filtrování tabulek
          MsgBox myDB.DCount("[ID]", "EmployeeData", "[Position] = 'Manager'")
          MsgBox myDB.DCount("[ID]", "EmployeeData", "[Position] = 'Sales' AND [City] = 'Chicago'")
          MsgBox myDB.DCount("[ID]", "EmployeeData", "[FirstName] LIKE 'Paul%'")

##### V Pythonu

          myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")
          bas = CreateScriptService("Basic")
          bas.MsgBox(myDB.DCount("[ID]", "EmployeeData"))
          bas.MsgBox(myDB.DSum("[Salary]", "EmployeeData"))
          bas.MsgBox(myDB.DCount("[ID]", "EmployeeData", "[Position] = 'Manager'"))
          bas.MsgBox(myDB.DCount("[ID]", "EmployeeData", "[Position] = 'Sales' AND [City] = 'Chicago'"))
          bas.MsgBox(myDB.DCount("[ID]", "EmployeeData", "[FirstName] LIKE 'Paul%'"))

## DLookup

Vyhodnotí SQL výraz pro jediný záznam vrácený klauzulí WHERE definovanou v parametru Criteria.

Jestliže dotaz vrátí více záznamů, uvažuje se pouze první z nich. Parametrem OrderClause určíte, jak se mají výsledky řadit.

### Syntaxe:

db.DLookup(expression: str, tablename: str, [criteria:str], [orderclause: str]): any

### Parametry:

expression: SQL příkaz s názvy polí uzavřenými v hranatých závorkách.

tablename: Název tabulky (bez hranatých závorek).

criteria: Klauzule WHERE bez klíčového slova "WHERE", názvy polí jsou uzavřeny v hranatých závorkách.

orderclause: Klauzule ORDER BY bez klíčových slov "ORDER BY". Názvy polí by měly být uzavřeny v hranatých závorkách.

### Příklad:

##### V Basicu

          MsgBox myDB.DLookup("[FirstName]", "EmployeeData", Criteria := "[LastName] LIKE 'Smith'", OrderClause := "[FirstName] DESC")
          MsgBox myDB.DLookup("[Salary]", "EmployeeData", Criteria := "[ID] = '3'")
          MsgBox myDB.DLookup("[Quantity] * [Value]", "Sales", Criteria := "[SaleID] = '5014'")

##### V Pythonu

          bas = CreateScriptService("Basic")
          bas.MsgBox(myDB.DLookup("[FirstName]", "EmployeeData", criteria = "[LastName] LIKE 'Smith'", orderclause = "[FirstName] DESC"))
          bas.MsgBox(myDB.DLookup("[Salary]", "EmployeeData", criteria = "[ID] = '3'"))
          bas.MsgBox(myDB.DLookup("[Quantity] * [Value]", "Sales", criteria = "[SaleID] = '5014'"))

## GetRows

Uloží do dvourozměrného pole obsah tabulky nebo výsledek dotazu SELECT či SQL příkazu. První index tohoto pole odpovídá řádkům, druhý index sloupcům.

Pro počet vrácených řádků lze stanovit horní limit. Volitelně mohou být do prvního řádku pole vloženy názvy sloupců.

Vrácené pole bude prázdné, pokud nejsou vráceny žádné řádky a zároveň není požadováno záhlaví sloupců.

### Syntaxe:

db.GetRows(sqlcommand: str, directsql: bool = False, header: bool = False, maxrows: int = 0): any

### Parametry:

sqlcommand: Název tabulky nebo dotazu (bez hranatých závorek) nebo SQL příkaz SELECT.

directsql: Je-li True, SQL příkaz se odešle databázovému enginu bez předchozí analýzy. Výchozí je False. U tabulek se tento argument ignoruje. U dotazů se použije taková možnost, jaká byly nastavena při definování dotazu.

header: Je-li True, bude první řádek vráceného pole obsahovat záhlaví sloupců.

maxrows: Maximální počet vrácených řádků. Výchozí hodnota je nula, což znamená, že počet vrácených řádků není omezen.

### Příklad:

Níže je několik příkladů použití metody GetRows:

##### V Basicu

          Dim queryResults as Variant
          ' Vrátí všechny řádky tabulky se záhlavím sloupců
          queryResults = myDB.GetRows("EmployeeData", Header := True)
          ' Vrátí prvních 50 záznamů o zaměstnancích seřazených podle pole 'FirstName'
          queryResults = myDB.GetRows("SELECT * FROM EmployeeData ORDER BY [FirstName]", MaxRows := 50)

##### V Pythonu

          queryResults = myDB.GetRows("EmployeeData", header = True)
          queryResults = myDB.GetRows("SELECT * FROM EmployeeData ORDER BY [FirstName]", maxrows = 50)

## RunSql

Provede akci z SQL příkazu, kterou může být vytvoření tabulky či vložení, aktualizace nebo smazání záznamů.

Metoda vrátí v případě úspěšného provedení True.

Pokud byla databáze otevřena v režimu pouze pro čtení, bude metoda RunSql zamítnuta s chybovou zprávou.

### Syntaxe:

db.RunSql(sqlcommand: str, directsql: bool = False): bool

### Parametry:

sqlcommand: Název dotazu (bez hranatých závorek) nebo SQL příkazu.

directsql: Je-li True, SQL příkaz se odešle databázovému enginu bez předchozí analýzy (výchozí = False). U dotazů se použije taková možnost, jaká byly nastavena při definování dotazu.

### Příklad:

##### V Basicu

          myDatabase.RunSql("INSERT INTO [EmployeeData] VALUES(25, 'Smith', 'John')", DirectSQL := True)

##### V Pythonu

          myDatabase.RunSql("INSERT INTO [EmployeeData] VALUES(25, 'Smith', 'John')", directsql = True)

Všechny procedury nebo identifikátory knihovny ScriptForge, které jsou uvozeny podtržítkem "_", jsou určeny pro interní použití. Není zamýšleno je používat v makrech Basicu nebo skriptech Pythonu.

Související témata

Služba SFDocuments.Document

Služba SFDocuments.Form

Služba ScriptForge.UI