Inhalte

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

- Erhält Zugriff auf Daten in Datenbanktabellen.

- Führt Abfragen SELECT und Aggregatfunktionen aus.

- Führt SQL-Aktionsanweisungen wie INSERT, UPDATE, DELETE, … aus.

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.

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.

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.

## Transaction handling

By default the database handles transactions in auto-commit mode, meaning that a commit is done after every SQL statement.

Use the SetTransactionMode method to change the default behavior, which allows for manual commits and rollbacks.

The methods Commit and Rollback are used to delimit transactions.

In LibreOffice, there are five types of transaction isolation modes, as defined in the com.sun.star.sdbc.TransactionIsolation constant group:

Constant | Value | Interpretation
--- | --- | ---
NONE | 0 | Transaction handling is disabled and the database is set to the default auto-commit mode.
READ_UNCOMMITTED | 1 | Dirty reads, non-repeatable reads and phantom reads can occur. If a row is changed by a transaction, another transaction will be able to read these changes even if they have not been committed.
READ_COMMITTED | 2 | Dirty reads are prevented, however non-repeatable reads and phantom reads can occur. This level prevents that rows with uncommitted changes are read.
REPEATABLE_READ | 4 | Dirty reads and non-repeatable reads are prevented. However, phantom reads can occur. Besides preventing uncommitted data from being read, it also prevents that two read operations in the same transaction return different results.
SERIALIZABLE | 8 | Dirty reads, non-repeatable reads and phantom reads are prevented. In addition to the constraints of the previous level, it also ensures that the set of records that match a WHERE clause remains unchanged inside the same transaction.

Read the Wikipedia page on Isolation in Database Systems to learn more about transaction integrity.

## Dienstaufruf

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

• 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

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

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

Commits all updates done since the previous Commit or Rollback call.

This method is ignored if commits are done automatically after each SQL statement, i.e. the database is set to the default auto-commit mode.

### Syntax:

db.Commit()

### Beispiel:

##### In Basic

          ' Set the REPEATABLE_READ transaction level
          myDB.SetTransactionMode(4)
          myDB.RunSql("UPDATE ...")
          myDB.Commit()
          myDB.RunSql("DELETE ...")
          ' Test some condition before committing
          If bSomeCondition Then
              myDB.Commit()
          Else
              myDB.Rollback()
          End If
          ' Restore auto-commit mode
          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

Creates a Dataset service instance based on a table, query or SQL SELECT statement.

### Syntax:

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

### Parameter:

sqlcommand: A table name, a query name or a valid SQL SELECT statement. Identifiers may be enclosed with square brackets. This argument is case-sensitive.

directsql: Set this argument to True to send the statement directly to the database engine without preprocessing by LibreOffice (Default = False).

filter: Specifies the condition that records must match to be included in the returned dataset. This argument is expressed as a SQL WHERE statement without the "WHERE" keyword.

orderby: Specifies the ordering of the dataset as a SQL ORDER BY statement without the "ORDER BY" keyword.

### Beispiel:

The following examples in Basic and Python return a dataset with the records of a table named "Customers".

##### In Basic

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

##### In Python

          dataset = myDatabase.CreateDataset("Customers", 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

Opens the specified form document in normal mode. This method returns a FormDocument service instance corresponding to the specified form document.

If the form document is already open, the form document window is activated.

If the specified form document does not exist, then Nothing is returned.

### Syntax:

svc.OpenFormDocument(formdocument: str): svc

### Parameter:

formdocument: The name of the FormDocument to be opened, as a case-sensitive string.

### Beispiel:

##### In Basic

Most form documents are stored in the root of the Base document and they can be opened simply using their names, as in the example below:

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

If form documents are organized in folders, it becomes necessary to include the folder name to specify the form document to be opened, as illustrated in the following example:

        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

Cancels all changes made to the database since the last Commit or Rollback call.

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

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

Defines the level of isolation in database transactions.

By default databases manage transactions in auto-commit mode, which means that a Commit is automatically performed after every SQL statement.

Use this method to manually determine the isolation level of transactions. When a transaction mode other than NONE is set, the script has to explicitly call the Commit method to apply the changes to the database.

This method returns True when successful.

Changing the transaction mode closes all Dataset instances created from the current database.

### Syntax:

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

### Parameter:

transactionmode: Specifies the transaction mode. This argument must be one of the constants defined in com.sun.star.sdbc.TransactionIsolation (Default = NONE)

Read the section Transaction handling above to learn more about the transaction isolation levels used in LibreOffice.

### Beispiel:

##### In Basic

          myDB.SetTransactionMode(com.sun.star.sdbc.TransactionIsolation.REPEATABLE_READ)
          oDataset = myDB.CreateDataset("SELECT ...")
          ' ...
          ' Reset the transaction mode to default
          myDB.SetTransactionMode()

##### In Python

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

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.

Verwandte Themen

Dienst SFDatabases.Datasheet

SFDatabases.Dataset service

Dienst SFDocuments.Document

Dienst SFDocuments.Form

Dienst ScriptForge.UI