Dienst SFDatabases.Database

Der Dienst Database bietet Zugriff auf Datenbanken, die entweder eingebettet oder in Base-Dokumenten beschrieben sind. Dieser Dienst bietet Methoden für Folgendes:

Jede Instanz des Dienstes Database stellt eine einzelne Datenbank dar und gewährt Zugriff auf ihre Tabellen, Abfragen und Daten.

Dieser Dienst bietet keinen Zugriff auf Formulare oder Berichte im Base-Dokument, das die Datenbank enthält. Um auf Formulare in einem Base-Dokument zuzugreifen, verwenden Sie die Methode FormDocuments des Dienstes Base.

note

Der gesamte Austausch zwischen diesem Dienst und der Datenbank erfolgt ausschließlich über SQL.


SQL-Anweisungen können im direkten oder indirekten Modus ausgeführt werden. Im direkten Modus wird die Anweisung ohne Syntaxprüfung oder -überprüfung an die Datenbank-Engine übertragen.

Die bereitgestellten Schnittstellen umfassen einfache Tabellen und Abfragelisten sowie den Zugriff auf Datenbankdaten.

tip

Um SQL-Anweisungen besser lesbar zu machen, können Sie eckige Klammern "[]" verwenden, um Namen von Tabellen, Abfragen und Feldern einzuschließen, anstatt andere einschließende Zeichen zu verwenden, die möglicherweise nur für bestimmte relationale Datenbankverwaltungssysteme (RDBMS) gelten. Beachten Sie jedoch, dass umschließende Zeichen in diesem Zusammenhang obligatorisch sind.


Transaktionsverarbeitung

Standardmäßig verarbeitet die Datenbank Transaktionen im Modus "auto-commit", was bedeutet, dass nach jeder SQL-Anweisung ein Commit durchgeführt wird.

Verwenden Sie die Methode SetTransactionMode, um das Standardverhalten zu ändern, das manuelle Commits und Rollbacks ermöglicht.

Zur Abgrenzung von Transaktionen werden die Methoden Commit und Rollback verwendet.

In LibreOffice gibt es fünf Arten von Transaktionsisolationsmodi, wie in der Konstantengruppe com.sun.star.sdbc.TransactionIsolation definiert:

Konstante

Wert

Interpretation

NONE

0

Transaktionsverarbeitung ist deaktiviert und die Datenbank ist auf den standardmäßigen Modus "auto-commit" eingestellt.

READ_UNCOMMITTED

1

Es können "dirty reads", "non-repeatable reads" und "phantom reads" auftreten.

Wenn eine Zeile durch eine Transaktion geändert wird, kann eine andere Transaktion diese Änderungen lesen, auch wenn sie nicht festgeschrieben wurden.

READ_COMMITTED

2

Verhindert "dirty reads", es kann jedoch zu "non-repeatable reads" und "phantom reads" kommen.

Diese Ebene verhindert, dass Zeilen mit nicht festgeschriebenen Änderungen gelesen werden.

REPEATABLE_READ

4

Verhindert "dirty reads" und "non-repeatable reads". Es kann jedoch zu "phantom reads" kommen.

Verhindert nicht nur, dass nicht festgeschriebene Daten gelesen werden, sondern auch, dass zwei Lesevorgänge in derselben Transaktion unterschiedliche Ergebnisse zurückgeben.

SERIALIZABLE

8

Verhindert "dirty reads", "non-repeatable reads" und "phantom reads".

Zusätzlich zu den Einschränkungen der vorherigen Ebene wird auch sichergestellt, dass der Satz von Datensätzen, die einer Klausel WHERE entsprechen, innerhalb derselben Transaktion unverändert bleibt.


tip

Lesen Sie die Wikipedia-Seite zu Isolation in Datenbanksystemen, um mehr über Transaktionsintegrität zu erfahren.


Dienstaufruf

Vor der Verwendung des Dienstes Database muss die Bibliothek ScriptForge geladen oder importiert werden:

note

• Grundlegende Makros erfordern das Laden der Bibliothek ScriptForge mit der folgenden Anweisung:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python-Skripte erfordern einen Import aus dem Modul scriptforge:
from scriptforge import CreateScriptService


Syntax:

Um eine Instanz des Dienstes Database zu erstellen, können Sie die Methode CreateScriptService verwenden:

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

note

In der oben beschriebenen Syntax können Sie entweder "SFDatabases.Database" oder einfach "Database" als erstes Argument der Methode CreateScriptService verwenden.


Parameter:

filename: Der Name der Base-Datei. Muss in der Notation SF_FileSystem.FileNaming ausgedrückt werden.

registrationname: Der Name einer registrierten Datenbank. Wenn filename angegeben wird, sollte dieses Argument nicht verwendet werden.

Wenn hingegen registrationname angegeben ist, sollte der Parameter filename nicht definiert werden.

readonly: Legt fest, ob die Datenbank schreibgeschützt geöffnet wird (Standard = True).

user, password: Zusätzliche Verbindungsparameter zum Datenbankserver.

Beispiel:

In Basic

      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDatabase as Object
      Set myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      ' Abfragen, SQL-Anweisungen, … ausführen
      myDatabase.CloseDatabase()
    
In Python

      from scriptforge import CreateScriptService
      myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      # Abfragen, SQL-Anweisungen, … ausführen
      myDatabase.CloseDatabase()
    

Zugriff auf Datenbanken mit dem Dienst "UI"

Es ist auch möglich, über den Dienst ScriptForge.UI auf die mit einem Base-Dokument verknüpfte Datenbank zuzugreifen, wie in den folgenden Beispielen gezeigt:

In Basic

      Dim myDoc As Object, myDatabase As Object, ui As Object
      Set ui = CreateScriptService("UI")
      Set myDoc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      ' Benutzer und Kennwort werden unten angegeben, falls erforderlich
      Set myDatabase = myDoc.GetDatabase()
      ' Abfragen, SQL-Anweisungen, … ausführen
      myDatabase.CloseDatabase()
      myDoc.CloseDocument()
    
In Python

      ui = CreateScriptService("UI")
      doc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      # Benutzer und Kennwort werden unten angegeben, falls erforderlich
      myDatabase = doc.GetDatabase()
      # Abfragen, SQL-Anweisungen, … ausführen
      myDatabase.CloseDatabase()
      doc.CloseDocument()
    
tip

Die im obigen Beispiel verwendete Methode GetDatabase ist Teil von ScriptForges Dienst Base.


Eigenschaften

Name

Schreibgeschützt

Typ

Beschreibung

Queries

Ja

Matrix mit Zeichenfolgen

Die Liste der gespeicherten Abfragen.

Tables

Ja

Matrix mit Zeichenfolgen

Die Liste der gespeicherten Tabellen.

XConnection

Ja

XConnection

Das UNO-Objekt, welches die aktuelle Datenbankverbindung darstellt.

XMetaData

Ja

XDatabaseMetaData

Das UNO-Objekt, das die Metadaten darstellt, welche die Datenbanksystemattribute beschreiben.


Liste der Methoden im Datenbankdienst

CloseDatabase
Commit
CreateDataset
DAvg
DCount
DMin

DMax
DSum
DLookup
GetRows
OpenFormDocument
OpenQuery

OpenSql
OpenTable
Rollback
RunSql
SetTransactionMode


CloseDatabase

Schließt die aktuelle Datenbankverbindung.

Syntax:

db.CloseDatabase()

Beispiel:


    myDatabase.CloseDatabase() ' Basic
  

    myDatabase.CloseDatabase() # Python
  

Commit

Überträgt alle Aktualisierungen, die seit dem vorherigen Aufruf Commit oder Rollback durchgeführt wurden.

note

Diese Methode wird ignoriert, wenn Commits automatisch nach jeder SQL-Anweisung erfolgen, beispielsweise wenn die Datenbank auf den Modus "auto-commit" eingestellt ist.


Syntax:

db.Commit()

Beispiel:

In Basic

      ' Legen Sie die Transaktionsebene "REPEATABLE_READ" fest
      myDB.SetTransactionMode(4)
      myDB.RunSql("UPDATE ...")
      myDB.Commit()
      myDB.RunSql("DELETE ...")
      ' Testet eine Bedingung, bevor ein Commit durchgeführt wird
      If bSomeCondition Then
          myDB.Commit()
      Else
          myDB.Rollback()
      End If
      ' Stellt den Modus "auto-commit" wieder her
      myDB.SetTransactionMode()
    
In Python

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

CreateDataset

Erstellt eine Dienstinstanz Dataset basierend auf einer Tabelle, einer Abfrage oder einer SQL-Anweisung SELECT.

Syntax:

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

Parameter:

sqlcommand: Ein Tabellenname, ein Abfragename oder eine gültige SQL-Anweisung SELECT. Bezeichner können in eckige Klammern eingeschlossen werden. Bei diesem Argument wird die Groß-/Kleinschreibung beachtet.

directsql: Setzt dieses Argument auf True, um die Anweisung ohne Vorverarbeitung durch LibreOffice direkt an die Datenbank-Engine zu senden (Standard = False).

filter: Legt die Bedingung fest, die Datensätze erfüllen müssen, um in den zurückgegebenen Datenbestand aufgenommen zu werden. Dieses Argument wird als SQL-Anweisung WHERE ohne das Schlüsselwort "WHERE" ausgedrückt.

orderby: Legt die Reihenfolge des Datenbestandes als SQL-Anweisung ORDER BY ohne das Schlüsselwort "ORDER BY" fest.

Beispiel:

Die folgenden Beispiele in Basic und Python geben einen Datenbestand mit den Datensätzen einer Tabelle namens „Kunden“ zurück.

In Basic

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

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

DAvg, DCount, DMin, DMax, DSum

Berechnet die angegebene Aggregatfunktion für ein Feld oder einen Ausdruck, der zu einer Tabelle gehört.

Optional, die SQL-Klausel WHERE kann als Filter angegeben werden, der vor der Aggregatfunktion angewendet wird.

Syntax:

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

Parameter:

expression: Ein SQL-Ausdruck, in dem die Feldnamen in eckige Klammern eingeschlossen sind.

tablename: Ein Tabellenname (ohne eckige Klammern).

criteria: Eine Klausel WHERE ohne das Schlüsselwort "WHERE", in der Feldnamen in eckige Klammern eingeschlossen sind.

Beispiel:

Das folgende Beispiel geht davon aus, dass die Datei Employees.odb eine Tabelle mit dem Namen EmployeeData enthält.

In Basic

      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDB as Variant
      Set myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")
      ' Zählt die Anzahl der Mitarbeiter in der Tabelle
      MsgBox myDB.DCount("[ID]", "EmployeeData")
      ' Gibt die Summe aller Gehälter in der Tabelle zurück
      MsgBox myDB.DSum("[Salary]", "EmployeeData")
      ' Im Folgenden finden Sie einige Beispiele dafür, wie Tabellen gefiltert werden können
      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%'")
    
In 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

Berechnet einen SQL-Ausdruck für einen einzelnen Datensatz, der von einer Klausel WHERE zurückgegeben wird, die durch den Parameter Criteria definiert ist.

Wenn die Abfrage mehrere Datensätze zurückgibt, wird nur der erste berücksichtigt. Verwenden Sie den Parameter OrderClause, um festzulegen, wie die Abfrageergebnisse sortiert werden.

Syntax:

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

Parameter:

expression: Ein SQL-Ausdruck, in dem die Feldnamen in eckige Klammern eingeschlossen sind.

tablename: Ein Tabellenname (ohne eckige Klammern).

criteria: Eine Klausel WHERE ohne das Schlüsselwort "WHERE", in der Feldnamen in eckige Klammern eingeschlossen sind.

orderclause: Eine Klausel ORDER BY ohne die Schlüsselwörter "ORDER BY". Feldnamen sollten in eckige Klammern eingeschlossen werden.

Beispiel:

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

Speichert den Inhalt einer Tabelle oder die Ergebnisse einer Abfrage SELECT oder einer SQL-Anweisung in einer zweidimensionalen Matrix. Der erste Index in der Matrix entspricht den Zeilen und der zweite Index bezieht sich auf die Spalten.

Für die Anzahl der zurückgegebenen Zeilen kann eine Obergrenze angegeben werden. Optional können Spaltennamen in die erste Zeile der Matrix eingefügt werden.

Die zurückgegebene Matrix ist leer, wenn keine Zeilen zurückgegeben werden und die Spaltenüberschriften nicht erforderlich sind.

Syntax:

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

Parameter:

sqlcommand: Ein Tabellen- oder Abfragename (ohne eckige Klammern) oder eine SQL-Anweisung SELECT.

directsql: Bei True wird der SQL-Befehl ohne Voranalyse an die Datenbank-Engine gesendet. Der Standardwert ist False. Dieses Argument wird für Tabellen ignoriert. Bei Abfragen ist die angewandte Option diejenige, die festgelegt wurde, als die Abfrage definiert wurde.

header: Wenn True, enthält die erste Zeile der zurückgegebenen Matrix die Spaltenüberschriften.

maxrows: Die maximale Anzahl der zurückzugebenden Zeilen. Der Standardwert ist null, was bedeutet, dass die Anzahl der zurückgegebenen Zeilen unbegrenzt ist.

Beispiel:

Im Folgenden finden Sie einige Beispiele dafür, wie die Methode GetRows verwendet werden kann:

In Basic

      Dim queryResults as Variant
      ' Gibt alle Zeilen in der Tabelle mit Spaltenüberschriften zurück
      queryResults = myDB.GetRows("EmployeeData", Header := True)
      ' Gibt die ersten 50 Mitarbeiterdatensätze geordnet nach dem Feld 'FirstName' zurück
      queryResults = myDB.GetRows("SELECT * FROM EmployeeData ORDER BY [FirstName]", MaxRows := 50)
    
In Python

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

OpenFormDocument

Öffnet das angegebene Formulardokument im normalen Modus. Diese Methode gibt eine Dienstinstanz FormDocument zurück, die dem angegebenen Formulardokument entspricht.

Wenn das Formulardokument bereits geöffnet ist, wird das Fenster des Formulardokuments aktiviert.

Wenn das angegebene Formulardokument nicht existiert, wird Nothing zurückgegeben.

Syntax:

svc.OpenFormDocument(formdocument: str): svc

Parameter:

formdocument: Der Name des FormDocument, das geöffnet werden soll, als Zeichenfolge, bei der die Groß-/Kleinschreibung beachtet wird.

Beispiel:

In Basic

Die meisten Formulardokumente werden im Stammverzeichnis des Basic-Dokuments gespeichert und können einfach über ihren Namen geöffnet werden, wie im folgenden Beispiel:


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

Wenn Formulardokumente in Ordnern organisiert sind, muss der Ordnername angegeben werden, um das zu öffnende Formulardokument anzugeben, wie im folgenden Beispiel dargestellt:


    oFormDoc = myDB.OpenFormDocument("myFolder/myFormDocument")
  
In Python

    formDoc = myDB.OpenFormDocument("myFormDocument")
  

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

OpenQuery

Öffnet das Fenster Datenansicht der angegebenen Abfrage und gibt eine Instanz des Dienstes Datasheet zurück.

Wenn die Abfrage nicht geöffnet werden konnte, wird Nothing zurückgegeben.

Syntax:

db.OpenQuery(queryname: str): obj

Parameter:

queryname: Der Name einer bestehenden Abfrage als Zeichenfolge unter Berücksichtigung der Groß- und Kleinschreibung.

Beispiel:

In Basic

      myDatabase.OpenQuery("MyQuery")
    
In Python

      myDatabase.OpenQuery("MyQuery")
    

OpenSql

Führt einen SQL-Befehl SELECT aus, öffnet ein Fenster Datenansicht mit den Ergebnissen und gibt eine Instanz des Dienstes Datasheet zurück.

Syntax:

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

Parameter:

sql: Eine Zeichenfolge, die eine gültige SQL-Anweisung SELECT enthält. Bezeichner können in eckige Klammern eingeschlossen werden.

directsql: Bei True wird der SQL-Befehl ohne Voranalyse an die Datenbank-Engine gesendet (Standard = False).

Beispiel:

In Basic

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

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

OpenTable

Öffnet das Fenster Datenansicht der angegebenen Tabelle und gibt eine Instanz des Dienstes Datasheet zurück.

Syntax:

db.OpenTable(tablename: str): obj

Parameter:

tablename: Der Name einer bestehenden Tabelle als Zeichenfolge unter Berücksichtigung der Groß- und Kleinschreibung.

Beispiel:

In Basic

      myDatabase.OpenTable("MyTable")
    
In Python

      myDatabase.OpenTable("MyTable")
    

Rollback

Macht alle seit dem letzten Aufruf von Commit oder Rollback an der Datenbank vorgenommenen Änderungen rückgängig.

Syntax:

db.Rollback()

Beispiel:

In Basic

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

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

RunSql

Führt eine Aktionsabfrage einer SQL-Anweisung aus, beispielsweise das Erstellen einer Tabelle sowie das Einfügen, Aktualisieren und Löschen von Datensätzen.

Die Methode gibt bei Erfolg True zurück.

tip

Die Methode RunSql wurde mit einer Fehlermeldung abgelehnt, falls die Datenbank zuvor im Modus "read-only" geöffnet wurde.


Syntax:

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

Parameter:

sqlcommand: Ein Abfragename (ohne eckige Klammern) oder eine SQL-Anweisung.

directsql: Bei True wird der SQL-Befehl ohne Voranalyse an die Datenbank-Engine gesendet. (Standard = False). Bei Abfragen ist die angewandte Option diejenige, die festgelegt wurde, als die Abfrage definiert wurde.

Beispiel:

In Basic

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

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

SetTransactionMode

Legt den Grad der Isolation bei Datenbanktransaktionen fest.

Standardmäßig verwalten Datenbanken Transaktionen im Modus "auto-Commit", was bedeutet, dass nach jeder SQL-Anweisung automatisch ein Commit durchgeführt wird.

Verwenden Sie diese Methode, um die Isolationsstufe von Transaktionen manuell zu bestimmen. Wenn ein anderer Transaktionsmodus als NONE festgelegt ist, muss das Skript explizit die Methode Commit aufrufen, um die Änderungen auf die Datenbank anzuwenden.

Diese Methode gibt bei Erfolg True zurück.

warning

Beim Ändern des Transaktionsmodus werden alle aus dem aktuellen Datenbestand erstellten Instanzen Dataset geschlossen.


Syntax:

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

Parameter:

transactionmode: Gibt den Transaktionsmodus an. Dieses Argument muss eine der in com.sun.star.sdbc.TransactionIsolation definierten Konstanten sein ( Standard = NONE)

note

Lesen Sie den Abschnitt Transaktionsverarbeitung oben, um mehr über die in LibreOffice verwendeten Transaktionsisolationsstufen zu erfahren.


Beispiel:

In Basic

      myDB.SetTransactionMode(com.sun.star.sdbc.TransactionIsolation.REPEATABLE_READ)
      oDataset = myDB.CreateDataset("SELECT ...")
      ' ...
      ' Setzt den Transaktionsmodus auf die Standardeinstellung zurück
      myDB.SetTransactionMode()
    
In Python

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

Alle ScriptForge Basic-Routinen oder Bezeichner, denen ein Unterstrich "_" vorangestellt ist, sind für den internen Gebrauch reserviert. Sie sind nicht für die Verwendung in Basic-Makros oder Python-Skripten vorgesehen.


Bitte unterstützen Sie uns!