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é.

Provádění transakcí

Ve výchozím nastavení provádí databáze transakce v režimu automatických potvrzování, což znamená, že se potvrzení provede po každém SQL příkazu.

Výchozí chování můžete změnit metodou SetTransactionMode a nastavit tak pro změny ruční potvrzování (commit) a odvolávání (rollback).

Pro vymezení transakcí se používají metody Commit a Rollback.

V Collabora Office je k dispozici pět režimů izolace transakcí, jak jsou definovány skupinou konstant com.sun.star.sdbc.TransactionIsolation:

Konstanta	Hodnota	Význam
NONE	0	Provádění transakcí není nastaveno a databáze je nastavena na režim automatického potvrzování.
READ_UNCOMMITTED	1	Může docházet ke špinavému čtení, neopakovatelnému čtení a čtení fantomů. Pokud je řádek transakcí změněn, může tyto změny číst jiná transakce, i když ještě nebyla potvrzena.
READ_COMMITTED	2	Je zabráněno špinavému čtení, avšak může docházet k neopakovatelnému čtení nebo čtení fantomů. Tato úroveň zabraňuje tomu, aby byly čteny řádky s nepotvrzenými změnami.
REPEATABLE_READ	4	Je zabráněno špinavému čtení a neopakovatelnému čtení, avšak může docházet ke čtení fantomů. Kromě tomu, že je zabráněno čtení nepotvrzených dat, je také zabráněno tomu, aby dvě operace čtení v téže transakci vrátily odlišné výsledky.
SERIALIZABLE	8	Je zabráněno špinavému čtení, neopakovatelnému čtení a čtení fantomů. Kromě omezením z předchozí úrovně je také zajištěno, že sada záznamů odpovídajících klauzuli WHERE zůstane během téže transakce nezměněna.

Podrobnosti o integritě transakce naleznete v angličtině v článku Wikipedie Isolation in Database Systems.

Volání služby

Před používáním služby Database je nutné načíst či naimportovat knihovnu ScriptForge pomocí:

• V makrech Basicu je nutné načíst knihovnu ScriptForge následujícím příkazem:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Ve skriptech Pythonu je nezbytné import z modulu scriptforge:
from scriptforge import CreateScriptService

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 Commit CreateDataset DAvg DCount DMin	DMax DSum DLookup GetRows OpenFormDocument OpenQuery	OpenSql OpenTable Rollback RunSql SetTransactionMode

CloseDatabase

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

Syntaxe:

db.CloseDatabase()

Příklad:

myDatabase.CloseDatabase() ' Basic

myDatabase.CloseDatabase() # Python

Commit

Potvrdí všechny aktualizace provedené od posledního volání metody Commit nebo Rollback.

Tato metoda se ignoruje v případě, že se potvrzování změn provádí po každém SQL příkazu automaticky, tj. je-li databáze nastavena na tento režim.

Syntaxe:

db.Commit()

Příklad:

V Basicu

' Nastaví úroveň transakcí REPEATABLE_READ
myDB.SetTransactionMode(4)
myDB.RunSql("UPDATE ...")
myDB.Commit()
myDB.RunSql("DELETE ...")
' Otestuje před potvrzením nějakou podmínku
If bSomeCondition Then
    myDB.Commit()
Else
    myDB.Rollback()
End If
' Obnoví režim automatického potvrzování
myDB.SetTransactionMode()

V Pythonu

myDB.SetTransactionMode(4)
myDB.RunSql("UPDATE ...")
myDB.Commit()
myDB.RunSql("DELETE ...")
if some_condition:
    myDB.Commit()
else:
    myDB.Rollback()
myDB.SetTransactionMode()

CreateDataset

Vytvoří instanci služby Dataset založenou na tabulce, dotazu nebo SQL příkazu SELECT.

Syntaxe:

db.CreateDataset(sqlcommand: str, opt directsql: bool, opt filter: str, opt orderby: str): svc

Parametry:

sqlcommand: Název tabulky či dotazu nebo platný SQL příkaz SELECT. Identifikátory mohou být uzavřeny v hranatých závorkách. U toho argumentu se rozlišuje velikost písmen.

directsql: Nastavte tento argument na True, chcete-li poslat příkaz přímo databázovém enginu místo toho, aby byl předzpracován programem Collabora Office (výchozí = False).

filter: Určuje podmínku, kterou musí záznamy splnit, aby byly zahrnuty do vrácené datové sady. Tento argument je vyjádřen jako SQL příkaz WHERE bez klíčového slova „WHERE“.

orderby: Určuje řazení datové sady jako SQL příkaz ORDER BY bez klíčového slova „ORDER BY“.

Příklad:

V následujících příkladech v Basicu a Pythonu se vrátí datová sada se záznamy z tabulky pojmenované „Customers“.

V Basicu

oDataset = myDatabase.CreateDataset("Customers", Filter := "[Name] LIKE 'A'")

V Pythonu

dataset = myDatabase.CreateDataset("Customers", Filter = "[Name] LIKE 'A'")

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)

OpenFormDocument

Otevře určený dokument formulářů v běžném režimu. Metoda vrátí instanci služby FormDocument, která odpovídá určenému dokumentu formulářů.

Pokud je dokument formulářů již otevřen, aktivuje se jeho okno.

Jestliže určený dokument neexistuje, vrátí se Nothing.

Syntaxe:

svc.OpenFormDocument(formdocument: str): svc

Parametry:

formdocument: Název objektu FormDocument, který se má otevřít, jako řetězec, u něhož se rozlišuje velikost písmen.

Příklad:

V Basicu

Většina dokumentů formulářů je uložena v kořeni dokumentu Base, a proto je lze otevřít pouze pomocí názvu, tak jako v následujícím příkladu:

Dim oFormDoc As Object
oFormDoc = myDB.OpenFormDocument("myFormDocument")

Pokud jsou dokumenty uspořádány ve složkách, je nezbytné při určení názvu dokumentu formulářů uvést název složky, jak ukazují následující příklady:

oFormDoc = myDB.OpenFormDocument("myFolder/myFormDocument")

V Pythonu

formDoc = myDB.OpenFormDocument("myFormDocument")

formDoc = myDB.OpenFormDocument("myFolder/myFormDocument")

OpenQuery

Otevře pro zadaný dotaz okno Pohled na data a vrátí instanci služby Datasheet.

Pokud dotaz nelze otevřít, vrátí se Nothing.

Syntaxe:

db.OpenQuery(queryname: str): obj

Parametry:

queryname: Název existujícího dotazu jako řetězec, u něhož se rozlišuje velikost písmen.

Příklad:

V Basicu

myDatabase.OpenQuery("MyQuery")

V Pythonu

myDatabase.OpenQuery("MyQuery")

OpenSql

Spustí příkaz SQL SELECT, otevře okno Pohled na data s výsledky a vrátí instanci služby Datasheet.

Syntaxe:

db.OpenSql(sql: str, directsql: bool): obj

Parametry:

sql: Řetězec obsahující platný příkaz SQL SELECT. Identifikátory je možné uzavřít do hranatých závorek.

directsql: Je-li True, SQL příkaz se odešle databázovému enginu bez předchozí analýzy (výchozí = False).

Příklad:

V Basicu

myDatabase.OpenSql("SELECT * FROM [Customers] ORDER BY [CITY]")

V Pythonu

myDatabase.OpenSql("SELECT * FROM [Customers] ORDER BY [CITY]")

OpenTable

Otevře okno Pohled na data se zadanou tabulkou a vrátí instanci služby Datasheet.

Syntaxe:

db.OpenTable(tablename: str): obj

Parametry:

tablename: Název existující tabulky jako řetězec, u něhož se rozlišuje velikost písmen.

Příklad:

V Basicu

myDatabase.OpenTable("MyTable")

V Pythonu

myDatabase.OpenTable("MyTable")

Rollback

Odvolá všechny změny provedené v databázi od posledního volání metody Commit nebo Rollback.

Syntaxe:

db.Rollback()

Příklad:

V Basicu

myDB.SetTransactionMode(1)
myDB.RunSql("UPDATE ...")
' ...
If bSomeCondition Then
    myDB.Rollback()
End If

V Pythonu

myDB.SetTransactionMode(1)
myDB.RunSql("UPDATE ...")
# ...
if bSomeCondition:
    myDB.Rollback()

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)

SetTransactionMode

Určuje úroveň izolace pro databázové transakce.

Ve výchozím nastavení spravují databáze transakce v režimu automatického potvrzování, což znamená, že se po každém SQL příkazu automaticky provede Commit.

Pomocí této metody určíte úroveň izolace pro transakce ručně. Pokud je režim transakcí jiný než NONE, ve skriptu je nutné explicitně zavolat metodu Commit, aby se změny v databázi provedly.

V případě úspěšné změny vrátí metoda True.

Změna režimu transakcí uzavře všechny instance služby Dataset vytvořené z aktuální databáze.

Syntaxe:

db.SetTransactionMode(transactionmode: int = 0): bool

Parametry:

transactionmode: Určuje režim transakcí. Tento argument musí mít hodnotu některé z konstant definovaných v com.sun.star.sdbc.TransactionIsolation (výchozí = NONE)

Další informace o úrovních izolace transakcí v Collabora Office naleznete v předchozí části Zpracování transakcí.

Příklad:

V Basicu

myDB.SetTransactionMode(com.sun.star.sdbc.TransactionIsolation.REPEATABLE_READ)
oDataset = myDB.CreateDataset("SELECT ...")
' ...
' Obnoví režim transakcí na výchozí
myDB.SetTransactionMode()

V Pythonu

from com.sun.star.sdbc import TransactionIsolation
myDB.SetTransactionMode(TransactionIsolation.REPEATABLE_READ)
dataset = myDB.CreateDataset("SELECT ...")
# ...
myDB.SetTransactionMode()

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.

Služba SFDatabases.Datasheet

Služba SFDatabases.Dataset

Služba SFDocuments.Document

Služba SFDocuments.Form

Služba ScriptForge.UI