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.


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

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