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:

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.

note

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.

tip

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


Transaction handling

By default the database handles transactions in auto-commit mode, meaning that a commit is done after every SQL statement.

Use the SetTransactionMode method to change the default behavior, which allows for manual commits and rollbacks.

The methods Commit and Rollback are used to delimit transactions.

In LibreOfficeDev, there are five types of transaction isolation modes, as defined in the com.sun.star.sdbc.TransactionIsolation constant group:

Constant

Value

Interpretation

NONE

0

Transaction handling is disabled and the database is set to the default auto-commit mode.

READ_UNCOMMITTED

1

Dirty reads, non-repeatable reads and phantom reads can occur.

If a row is changed by a transaction, another transaction will be able to read these changes even if they have not been committed.

READ_COMMITTED

2

Dirty reads are prevented, however non-repeatable reads and phantom reads can occur.

This level prevents that rows with uncommitted changes are read.

REPEATABLE_READ

4

Dirty reads and non-repeatable reads are prevented. However, phantom reads can occur.

Besides preventing uncommitted data from being read, it also prevents that two read operations in the same transaction return different results.

SERIALIZABLE

8

Dirty reads, non-repeatable reads and phantom reads are prevented.

In addition to the constraints of the previous level, it also ensures that the set of records that match a WHERE clause remains unchanged inside the same transaction.


tip

Read the Wikipedia page on Isolation in Database Systems to learn more about transaction integrity.


Volání služby

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

note

• 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

note

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()
    
tip

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

Commits all updates done since the previous Commit or Rollback call.

note

This method is ignored if commits are done automatically after each SQL statement, i.e. the database is set to the default auto-commit mode.


Syntaxe:

db.Commit()

Příklad:

V Basicu

      ' Set the REPEATABLE_READ transaction level
      myDB.SetTransactionMode(4)
      myDB.RunSql("UPDATE ...")
      myDB.Commit()
      myDB.RunSql("DELETE ...")
      ' Test some condition before committing
      If bSomeCondition Then
          myDB.Commit()
      Else
          myDB.Rollback()
      End If
      ' Restore auto-commit mode
      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

Creates a Dataset service instance based on a table, query or SQL SELECT statement.

Syntaxe:

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

Parametry:

sqlcommand: A table name, a query name or a valid SQL SELECT statement. Identifiers may be enclosed with square brackets. This argument is case-sensitive.

directsql: Set this argument to True to send the statement directly to the database engine without preprocessing by LibreOfficeDev (Default = False).

filter: Specifies the condition that records must match to be included in the returned dataset. This argument is expressed as a SQL WHERE statement without the "WHERE" keyword.

orderby: Specifies the ordering of the dataset as a SQL ORDER BY statement without the "ORDER BY" keyword.

Příklad:

The following examples in Basic and Python return a dataset with the records of a table named "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

Cancels all changes made to the database since the last Commit or Rollback call.

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.

tip

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

Defines the level of isolation in database transactions.

By default databases manage transactions in auto-commit mode, which means that a Commit is automatically performed after every SQL statement.

Use this method to manually determine the isolation level of transactions. When a transaction mode other than NONE is set, the script has to explicitly call the Commit method to apply the changes to the database.

This method returns True when successful.

warning

Changing the transaction mode closes all Dataset instances created from the current database.


Syntaxe:

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

Parametry:

transactionmode: Specifies the transaction mode. This argument must be one of the constants defined in com.sun.star.sdbc.TransactionIsolation (Default = NONE)

note

Read the section Transaction handling above to learn more about the transaction isolation levels used in LibreOfficeDev.


Příklad:

V Basicu

      myDB.SetTransactionMode(com.sun.star.sdbc.TransactionIsolation.REPEATABLE_READ)
      oDataset = myDB.CreateDataset("SELECT ...")
      ' ...
      ' Reset the transaction mode to default
      myDB.SetTransactionMode()
    
V Pythonu

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

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.