Spis treści
Indeks 🔎︎

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

## 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 DAvg DCount DMin | DMax DSum DLookup GetRows | OpenQuery OpenSql OpenTable RunSql

## CloseDatabase

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

### Składnia:

db.CloseDatabase()

### Przykład:

        myDatabase.CloseDatabase() ' Basic

        myDatabase.CloseDatabase() # Python

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

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

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

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 SFDocuments.Document

Usługa SFDocuments.Form

Usługa ScriptForge.UI