Spis treści

# 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:

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.

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

### Składnia:

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.

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

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.

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.

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.

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)

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

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.

Tematy pokrewne

Usługa SFDatabases.Datasheet

Usługa SFDatabases.Dataset

Usługa SFDocuments.Document

Usługa SFDocuments.Form

Usługa ScriptForge.UI