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:

• Uzyskanie dostępu do danych w tabelach bazy danych.

• Uruchamianie kwerendy SELECT i wykonywanie funkcji agregujących.

• Uruchamianie instrukcji działania SQL, takich jak INSERT, UPDATE, DELETE itp.

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.

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.

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:

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:

• 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

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

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

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

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.

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

      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:

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

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

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

Właściwości

CloseDatabase

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

db.CloseDatabase()

    myDatabase.CloseDatabase() ' Basic
  

    myDatabase.CloseDatabase() # Python
  

Commit

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

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.

db.Commit()

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

      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.

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

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

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

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

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

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

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.

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

      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%'")
    

      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.

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

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.

      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'")
    

      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.

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

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.

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

      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)
    

      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.

svc.OpenFormDocument(formdocument: str): svc

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

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")
  

    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.

db.OpenQuery(queryname: str): obj

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

      myDatabase.OpenQuery("MyQuery")
    

      myDatabase.OpenQuery("MyQuery")
    

OpenSql

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

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

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

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

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

OpenTable

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

db.OpenTable(tablename: str): obj

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

      myDatabase.OpenTable("MyTable")
    

      myDatabase.OpenTable("MyTable")
    

Rollback

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

db.Rollback()

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

      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.

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

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

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.

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

      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.

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

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

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

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

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

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

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.