Usługa SFDatabases.Database

Usługa Database zapewnia dostęp do baz danych osadzonych lub opisanych w dokumentach Base. Usługa ta zapewnia metody umożliwiające:

Każda instancja usługi Database reprezentuje pojedynczą bazę danych i daje dostęp do jej tabel, zapytań i danych.

Usługa ta nie zapewnia dostępu do formularzy i raportów znajdujących się w dokumencie Base zawierającym bazę danych. Aby uzyskać dostęp do formularzy w dokumencie Base, zapoznaj się z metodą FormDocuments usługi Base.

note

Cała wymiana między tą usługą a bazą danych odbywa się wyłącznie przy użyciu SQL.


Instrukcje SQL mogą być uruchamiane w trybie bezpośrednim lub pośrednim. W trybie bezpośrednim instrukcja jest przesyłana do silnika bazy danych bez sprawdzania i przeglądania składni.

Dostarczone interfejsy obejmują proste tabele i listy kwerend, a także dostęp do danych z baz danych.

tip

Aby zwiększyć czytelność instrukcji SQL, można użyć nawiasów kwadratowych „[ ]” do ujęcia nazw tabel, kwerend i pól, zamiast używać innych znaków otaczających, które mogą być dostępne wyłącznie w niektórych systemach zarządzania relacyjnymi bazami danych (RDBMS). Należy jednak pamiętać, że w tym kontekście znaki otaczające są obowiązkowe.


Obsługa transakcji

Domyślnie baza danych obsługuje transakcje w trybie automatycznego zatwierdzania, co oznacza, że zatwierdzenie jest wykonywane po każdej instrukcji SQL.

Użyj metody SetTransactionMode, aby zmienić domyślne zachowanie, które pozwala na ręczne zatwierdzanie i wycofywanie zmian.

Metody Commit i Rollback służą do oddzielania transakcji.

W LibreOffice istnieje pięć typów trybów izolacji transakcji zdefiniowanych w grupie stałych com.sun.star.sdbc.TransactionIsolation:

Stała

Wartość

Interpretacja

NONE

0

Obsługa transakcji jest wyłączona, a baza danych ustawiona jest na domyślny tryb automatycznego zatwierdzania.

READ_UNCOMMITTED

1

Mogą wystąpić odczyty brudne, odczyty niepowtarzalne i odczyty fantomowe.

Jeśli wiersz zostanie zmieniony przez transakcję, inna transakcja będzie mogła odczytać te zmiany, nawet jeśli nie zostały one zatwierdzone.

READ_COMMITTED

2

Zapobiega błędnym odczytom, jednakże mogą wystąpić odczyty niepowtarzalne i odczyty fantomowe.

Ten poziom zapobiega odczytywaniu wierszy z niezatwierdzonymi zmianami.

REPEATABLE_READ

4

Zapobiega błędnym odczytom i odczytom niepowtarzalnym. Mogą jednak wystąpić odczyty fantomowe.

Oprócz zapobiegania odczytywaniu niezatwierdzonych danych, zapobiega także sytuacji, w której dwie operacje odczytu w tej samej transakcji zwracają różne wyniki.

SERIALIZABLE

8

Zapobiega odczytom brudnym, odczytom niepowtarzalnym i odczytom fantomowym.

Oprócz ograniczeń z poprzedniego poziomu zapewnia to również, że zestaw rekordów pasujących do klauzuli WHERE pozostanie niezmieniony w ramach tej samej transakcji.


tip

Przeczytaj stronę Wikipedii w języku angielskim na temat Izolacja w systemach baz danych, aby dowiedzieć się więcej o integralności transakcji.


Wywoływanie usługi

Przed użyciem usługi Database należy załadować lub zaimportować bibliotekę ScriptForge:

note

• Podstawowe makra wymagają załadowania biblioteki ScriptForge przy użyciu następującej instrukcji:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Skrypty Pythona wymagają importu z modułu scriptforge:
from scriptforge import CreateScriptService


Składnia:

Aby utworzyć instancję usługi Database możesz skorzystać z metody CreateScriptService:

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

note

W składni opisanej powyżej możesz użyć "SFDatabases.Database" lub po prostu "Database" jako pierwszego argumentu metody CreateScriptService.


Parametry:

filename: nazwa pliku Base. Należy wyrazić przy użyciu notacji SF_FileSystem.FileNaming.

registrationname: nazwa zarejestrowanej bazy danych. Jeśli podano filename, nie należy używać tego argumentu.

I odwrotnie, jeśli określono registrationname, nie należy definiować parametru filename.

readonly: określa, czy baza danych zostanie otwarta w trybie tylko do odczytu (domyślnie = True).

user, password: dodatkowe parametry połączenia z serwerem bazy danych.

Przykład:

W języku Basic

      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDatabase as Object
      Set myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      ' Uruchamiaj kwerendy, instrukcje SQL, ...
      myDatabase.CloseDatabase()
    
W języku Python

      from scriptforge import CreateScriptService
      myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      # Uruchamiaj kwerendy, instrukcje SQL, ...
      myDatabase.CloseDatabase()
    

Dostęp do baz danych za pomocą usługi interfejsu użytkownika

Dostęp do bazy danych powiązanej z dokumentem Base można także uzyskać za pomocą usługi ScriptForge.UI jak pokazano na poniższych przykładach:

W języku Basic

      Dim myDoc As Object, myDatabase As Object, ui As Object
      Set ui = CreateScriptService("UI")
      Set myDoc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      ' Poniżej znajduje się nazwa użytkownika i hasło w razie potrzeby
      Set myDatabase = myDoc.GetDatabase()
      ' Uruchamiaj kwerendy, instrukcje SQL, ...
      myDatabase.CloseDatabase()
      myDoc.CloseDocument()
    
W języku Python

      ui = CreateScriptService("UI")
      doc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      # W razie potrzeby poniżej podano użytkownika i hasło
      myDatabase = doc.GetDatabase()
      # Uruchamiaj kwerendy, instrukcje SQL, ...
      myDatabase.CloseDatabase()
      doc.CloseDocument()
    
tip

Metoda GetDatabase użyta w powyższym przykładzie jest częścią usługi Base ScriptForge.


Właściwości

Nazwa

Tylko do odczytu

Typ

Opis

Queries

Tak

Tablica ciągów

Lista przechowywanych kwerend.

Tables

Tak

Tablica ciągów

Lista przechowywanych tabel.

XConnection

Tak

XConnection

Obiekt UNO reprezentujący bieżące połączenie z bazą danych.

XMetaData

Tak

XDatabaseMetaData

Obiekt UNO reprezentujący metadane opisujące atrybuty systemu bazy danych.


Lista metod w usłudze Database

CloseDatabase
Commit
CreateDataset
DAvg
DCount
DMin

DMax
DSum
DLookup
GetRows
OpenFormDocument
OpenQuery

OpenSql
OpenTable
Rollback
RunSql
SetTransactionMode


CloseDatabase

Zamyka bieżące połączenie z bazą danych.

Składnia:

db.CloseDatabase()

Przykład:


    myDatabase.CloseDatabase() ' Basic
  

    myDatabase.CloseDatabase() # Python
  

Commit

Zatwierdza wszystkie aktualizacje wykonane od poprzedniego wywołania Commit lub Rollback.

note

Ta metoda jest ignorowana, jeśli zatwierdzenia są wykonywane automatycznie po każdej instrukcji SQL, tj. baza danych jest ustawiona na domyślny tryb automatycznego zatwierdzania.


Składnia:

db.Commit()

Przykład:

W języku Basic

      ' Ustaw poziom transakcji REPEATABLE_READ
      myDB.SetTransactionMode(4)
      myDB.RunSql("UPDATE ...")
      myDB.Commit()
      myDB.RunSql("DELETE ...")
      ' Przetestuj jakiś warunek przed zatwierdzeniem
      If bSomeCondition Then
          myDB.Commit()
      Else
          myDB.Rollback()
      End If
      ' Przywróć tryb automatycznego zatwierdzania
      myDB.SetTransactionMode()
    
W języku Python

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

CreateDataset

Tworzy instancję usługi Dataset na podstawie tabeli, kwerendy lub instrukcji SQL SELECT.

Składnia:

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

Parametry:

sqlcommand: nazwa tabeli, nazwa kwerendy lub prawidłowa instrukcja SQL SELECT. Identyfikatory można ująć w nawiasy kwadratowe. W tym argumencie rozróżniana jest wielkość liter.

directsql: ustaw ten argument na True, aby wysłać instrukcję bezpośrednio do silnika bazy danych bez wstępnego przetwarzania przez LibreOffice (domyślnie = False).

filter: określa warunek, który muszą spełnić rekordy, aby zostały uwzględnione w zwróconym zbiorze danych. Argument ten jest wyrażony jako instrukcja SQL WHERE bez słowa kluczowego "WHERE".

orderby: określa kolejność zbioru danych jako instrukcja SQL ORDER BY bez słowa kluczowego "ORDER BY".

Przykład:

Poniższe przykłady w języku Basic i Python zwracają zestaw danych zawierający rekordy tabeli o nazwie "Customers".

W języku Basic

      oDataset = myDatabase.CreateDataset("Customers", Filter := "[Name] LIKE 'A'")
    
W języku Python

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

DAvg, DCount, DMin, DMax, DSum

Oblicza daną funkcję agregującą w polu lub wyrażeniu należącym do tabeli.

Opcjonalnie można określić klauzulę SQL WHERE jako filtr, który zostanie zastosowany przed funkcją agregującą.

Składnia:

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: wyrażenie SQL, w którym nazwy pól są ujęte w nawiasy kwadratowe.

tablename: nazwa tabeli (bez nawiasów kwadratowych).

criteria: klauzula WHERE bez słowa kluczowego „WHERE”, w której nazwy pól są ujęte w nawiasy kwadratowe.

Przykład:

W poniższym przykładzie założono, że plik Employees.odb zawiera tabelę o nazwie EmployeeData.

W języku Basic

      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDB as Variant
      Set myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")
      ' Zlicza w tabeli liczbę pracowników
      MsgBox myDB.DCount("[ID]", "EmployeeData")
      ' Zwraca w tabeli sumę wszystkich wynagrodzeń
      MsgBox myDB.DSum("[Salary]", "EmployeeData")
      ' Poniżej znajduje się kilka przykładów filtrowania tabel
      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%'")
    
W języku Python

      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

Oblicza wyrażenie SQL na pojedynczym rekordzie zwróconym przez klauzulę WHERE zdefiniowaną przez parametr Criteria.

Jeśli kwerenda zwróci wiele rekordów, pod uwagę brana będzie tylko pierwsza z nich. Użyj parametru OrderClause, aby określić sposób sortowania wyników kwerendy.

Składnia:

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

Parametry:

expression: wyrażenie SQL, w którym nazwy pól są ujęte w nawiasy kwadratowe.

tablename: nazwa tabeli (bez nawiasów kwadratowych).

criteria: klauzula WHERE bez słowa kluczowego „WHERE”, w której nazwy pól są ujęte w nawiasy kwadratowe.

orderclause: klauzula ORDER BY bez słów kluczowych „ORDER BY”. Nazwy pól należy ująć w nawiasy kwadratowe.

Przykład:

W języku Basic

      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'")
    
W języku Python

      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

Przechowuje zawartość tabeli lub wyniki kwerendy SELECT albo instrukcji SQL w tablicy dwuwymiarowej. Pierwszy indeks w tablicy odpowiada wierszom, drugi zaś kolumnom.

Można określić górny limit liczby zwracanych wierszy. Opcjonalnie nazwy kolumn można wstawić w pierwszym wierszu tablicy.

Zwrócona tablica będzie pusta, jeśli nie zostaną zwrócone żadne wiersze, a główki kolumn nie są wymagane.

Składnia:

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

Parametry:

sqlcommand: nazwa tabeli lub kwerendy (bez nawiasów kwadratowych) albo instrukcja SQL SELECT.

directsql: gdy True, polecenie SQL jest wysyłane do silnika bazy danych bez wstępnej analizy. Wartość domyślna to False. Argument ten jest ignorowany w przypadku tabel. W przypadku kwerend zastosowaną opcją jest ta ustawiona podczas definiowania kwerendy.

header: gdy True, pierwszy wiersz zwróconej tablicy zawiera główki kolumn.

maxrows: maksymalna liczba wierszy do zwrócenia. Wartością domyślną jest zero, co oznacza, że nie ma ograniczenia liczby zwracanych wierszy.

Przykład:

Poniżej znajduje się kilka przykładów wykorzystania metody GetRows:

W języku Basic

      Dim queryResults as Variant
      ' Zwraca wszystkie wiersze tabeli z główkami kolumn
      queryResults = myDB.GetRows("EmployeeData", Header := True)
      ' Zwraca pierwszych 50 rekordów pracowników uporządkowanych według pola 'FirstName'.
      queryResults = myDB.GetRows("SELECT * FROM EmployeeData ORDER BY [FirstName]", MaxRows := 50)
    
W języku Python

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

OpenFormDocument

Otwiera określony dokument formularza w trybie normalnym. Ta metoda zwraca instancję usługi FormDocument odpowiadającą określonemu dokumentowi formularza.

Jeżeli dokument formularza jest już otwarty, aktywowane jest okno dokumentu formularza.

Jeśli określony dokument formularza nie istnieje, zwracane jest Nothing.

Składnia:

svc.OpenFormDocument(formdocument: str): svc

Parametry:

formdocument: nazwa FormDocument do otworzenia jako ciąg znaków, w którym rozróżniana jest wielkość liter.

Przykład:

W języku Basic

Większość dokumentów formularzy jest przechowywana w katalogu głównym dokumentu Base i można je otwierać, używając ich nazw, jak w poniższym przykładzie:


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

Jeśli dokumenty formularza są zorganizowane w folderach, konieczne staje się uwzględnienie nazwy folderu w celu określenia dokumentu formularza, który ma zostać otwarty, jak pokazano w poniższym przykładzie:


    oFormDoc = myDB.OpenFormDocument("myFolder/myFormDocument")
  
W języku Python

    formDoc = myDB.OpenFormDocument("myFormDocument")
  

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

OpenQuery

Otwiera okno Widok danych określonej kwerendy i zwraca instancję usługi Datasheet.

Jeżeli nie można było otworzyć kwerendy, zwracane jest Nothing.

Składnia:

db.OpenQuery(queryname: str): obj

Parametry:

queryname: nazwa istniejącej kwerendy jako ciąg znaków, w którym rozróżniana jest wielkość liter.

Przykład:

W języku Basic

      myDatabase.OpenQuery("MyQuery")
    
W języku Python

      myDatabase.OpenQuery("MyQuery")
    

OpenSql

Uruchamia polecenie SQL SELECT, otwiera okno Widoku danych z wynikami i zwraca instancję usługi Datasheet.

Składnia:

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

Parametry:

sql: ciąg zawierający prawidłową instrukcję SQL SELECT. Identyfikatory można ująć w nawiasy kwadratowe.

directsql: gdy True, polecenie SQL jest wysyłane do silnika bazy danych bez wstępnej analizy (domyślnie = False).

Przykład:

W języku Basic

      myDatabase.OpenSql("SELECT * FROM [Customers] ORDER BY [CITY]")
    
W języku Python

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

OpenTable

Otwiera okno Widok danych określonej tabeli i zwraca instancję usługi Datasheet.

Składnia:

db.OpenTable(tablename: str): obj

Parametry:

tablename: nazwa istniejącej tabeli jako ciąg tekstowy z rozróżnianiem wielkości liter.

Przykład:

W języku Basic

      myDatabase.OpenTable("MyTable")
    
W języku Python

      myDatabase.OpenTable("MyTable")
    

Rollback

Anuluje wszystkie zmiany wprowadzone w bazie danych od ostatniego wywołania Commit lub Rollback.

Składnia:

db.Rollback()

Przykład:

W języku Basic

      myDB.SetTransactionMode(1)
      myDB.RunSql("UPDATE ...")
      ' ...
      If bSomeCondition Then
          myDB.Rollback()
      End If
    
W języku Python

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

RunSql

Wykonuje kwerendę działania instrukcji SQL, takiej jak utworzenie tabeli, a także wstawianie, aktualizowanie i usuwanie rekordów.

Metoda zwraca wartość True, jeśli operacja się powiedzie.

tip

Metoda RunSql jest odrzucana z komunikatem o błędzie w przypadku, gdy baza danych była wcześniej otwarta w trybie tylko do odczytu.


Składnia:

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

Parametry:

sqlcommand: nazwa kwerendy (bez nawiasów kwadratowych) lub instrukcja SQL.

directsql: gdy True, polecenie SQL jest wysyłane do silnika bazy danych bez wstępnej analizy (domyślnie = False). W przypadku kwerend zastosowaną opcją jest ta ustawiona podczas definiowania kwerendy.

Przykład:

W języku Basic

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

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

SetTransactionMode

Określa poziom izolacji w transakcjach bazy danych.

Domyślnie bazy danych zarządzają transakcjami w trybie automatycznego zatwierdzania, co oznacza, że Commit jest wykonywane automatycznie po każdej instrukcji SQL.

Użyj tej metody, aby ręcznie określić poziom izolacji transakcji. Gdy ustawiony jest tryb transakcji inny niż NONE, skrypt musi jawnie wywołać metodę Commit, aby zastosować zmiany do bazy danych.

Ta metoda zwraca wartość True, jeśli operacja się powiedzie.

warning

Zmiana trybu transakcji powoduje zamknięcie wszystkich instancji Dataset utworzonych z bieżącej bazy danych.


Składnia:

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

Parametry:

transactionmode: określa tryb transakcji. Argument ten musi być jedną ze stałych zdefiniowanych w com.sun.star.sdbc.TransactionIsolation (domyślnie = NONE)

note

Przeczytaj sekcję Obsługa transakcji powyżej, aby dowiedzieć się więcej o poziomach izolacji transakcji stosowanych w LibreOffice.


Przykład:

W języku Basic

      myDB.SetTransactionMode(com.sun.star.sdbc.TransactionIsolation.REPEATABLE_READ)
      oDataset = myDB.CreateDataset("SELECT ...")
      ' ...
      ' Przywróć domyślny tryb transakcji
      myDB.SetTransactionMode()
    
W języku Python

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

Wszystkie podstawowe procedury lub identyfikatory ScriptForge poprzedzone znakiem podkreślenia „_” są zarezerwowane do użytku wewnętrznego. Nie należy ich używać w makrach Basic ani skryptach Pythona.


Prosimy o wsparcie!