SFDatabases.Database service

Inhoud

# SFDatabases.Database-service

De service Database biedt toegang tot databases die zijn ingesloten of beschreven in Base-documenten. Deze service biedt methodes om:

- Krijg toegang tot gegevens in databasetabellen.

- SELECT query's en aggregatiefuncties uitvoeren.

- SQL-instructies, zoals INSERT, UPDATE, DELETE, enz uitvoeren.

Elk exemplaar van de Database-service vertegenwoordigt een enkele database en geeft toegang tot de tabellen, query's en gegevens.

Deze service biedt geen toegang tot formulieren of rapporten in het basisdocument dat de database bevat. Om toegang te krijgen tot formulieren in een basisdocument, raadpleegt u de methode FormDocuments van de Base-service.

Alle uitwisselingen tussen deze service en de database gebeuren alleen met SQL.

SQL-instructies kunnen worden uitgevoerd in de modus direct of indirect. In de directe modus wordt de instructie overgebracht naar de database-engine zonder enige syntaxiscontrole of herziening.

De geboden interfaces omvatten eenvoudige tabellen en querylijsten, evenals toegang tot databasegegevens.

Om SQL-instructies leesbaarder te maken, kunt u vierkante haken "[ ]" gebruiken om namen van tabellen, query's en velden te omsluiten in plaats van andere omsluitende tekens te gebruiken die exclusief kunnen zijn voor bepaalde relationele databasebeheersystemen (RDBMS). Maar pas op dat het insluiten van tekens in deze context verplicht is.

## Transactieafhandeling

Standaard verwerkt de database transacties in de auto-commit-modus, wat betekent dat na elke SQL-instructie een commit wordt uitgevoerd.

Gebruik de methode SetTransactionMode om het standaardgedrag te wijzigen, waardoor handmatige commits en rollbacks mogelijk zijn.

De methodes Commit en Rollback worden gebruikt om transacties af te bakenen.

In LibreOffice zijn er vijf types transactie-isolatiemodi, zoals gedefinieerd in com.sun.star.sdbc .TransactionIsolation constante groep:

Constante | Waarde | Interpretatie
--- | --- | ---
NONE | 0 | Transactieafhandeling is uitgeschakeld en de database is ingesteld op de standaardmodus voor automatisch vastleggen.
READ_UNCOMMITTED | 1 | Er kunnen vuile leesbewerkingen, niet-herhaalbare leesbewerkingen en fantoomlezingen voorkomen. Als een rij door een transactie wordt gewijzigd, kan een andere transactie deze wijzigingen lezen, zelfs als deze niet zijn vastgelegd.
READ_COMMITTED | 2 | Vuile leesbewerkingen worden voorkomen, maar niet-herhaalbare leesbewerkingen en fantoomleesbewerkingen kunnen optreden. Dit niveau voorkomt dat rijen met niet-vastgelegde wijzigingen worden gelezen.
REPEATABLE_READ | 4 | Vuile leesbewerkingen en niet-herhaalbare leesbewerkingen worden voorkomen. Er kunnen echter fantoomlezingen optreden. Naast het voorkomen dat niet-vastgelegde gegevens worden gelezen, voorkomt het ook dat twee leesbewerkingen in dezelfde transactie verschillende resultaten opleveren.
SERIALIZABLE | 8 | Vuile leesbewerkingen, niet-herhaalbare leesbewerkingen en fantoomleesbewerkingen worden voorkomen. Naast de beperkingen van het vorige niveau zorgt het er ook voor dat de set records die overeenkomen met een WHERE-clausule binnen dezelfde transactie ongewijzigd blijft.

Lees de Wikipedia-pagina op Isolation (database systems) voor meer informatie over transactie-integriteit.

## Service aanroep

Voordat de service Database gebruikt kan worden, moet de bibliotheek ScriptForge eerst worden geladen of geïmporteerd:

• Basic macro's kunnen de bibliotheek ScriptForge laden met de instructie:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python scripts kunnen de module scriptforge importeren met:
from scriptforge import CreateScriptService

### Syntaxis:

Om een instantie van de Database-service te maken, kunt u de CreateScriptService-methode gebruiken:

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

In de hierboven beschreven syntaxis kunt u ofwel "SFDatabases.Database" of gewoon "Database" gebruiken als het eerste argument van de CreateScriptService-methode.

### Parameters:

filename: De naam van het basisbestand. Moet worden uitgedrukt met de notatie SF_FileSystem.FileNaming.

registrationname: De naam van een geregistreerde database. Als filename is opgegeven, mag dit argument niet worden gebruikt.

Omgekeerd, als een registrationname is opgegeven, moet de parameter filename niet worden gedefinieerd.

readonly: Bepaalt of de database wordt geopend als alleen-lezen (Standaard = True).

user, password: Aanvullende verbindingsparameters voor de databaseserver.

### Voorbeeld:

##### In BASIC

          GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
          Dim myDatabase as Object
          Set myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
          ' Query's, SQL statements, ... uitvoeren
          myDatabase.CloseDatabase()

##### In Python

          from scriptforge import CreateScriptService
          myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
          # Query's, SQL statements, ... uitvoeren
          myDatabase.CloseDatabase()

## Toegang tot databases met de UI-service

Het is ook mogelijk om toegang te krijgen tot de database die is gekoppeld aan een basisdocument met behulp van de ScriptForge.UI-service, zoals weergegeven in de onderstaande voorbeelden:

##### 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")
          ' Gebruiker en wachtwoord worden hieronder vermeld, indien nodig
          Set myDatabase = myDoc.GetDatabase()
          ' Query's, SQL statements, ... uitvoeren
          myDatabase.CloseDatabase()
          myDoc.CloseDocument()

##### In Python

          ui = CreateScriptService("UI")
          doc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
          # Gebruikersnaam en wachtwoord worden hieronder vermeld, indien nodig
          myDatabase = doc.GetDatabase()
          # Query's, SQL statements, ... uitvoeren
          myDatabase.CloseDatabase()
          doc.CloseDocument()

De methode GetDatabase die in het bovenstaande voorbeeld wordt gebruikt, maakt deel uit van ScriptForge's Base onderhoud.

## Eigenschappen

Naam | AlleenLezen | Type | Beschrijving
--- | --- | --- | ---
Queries | Ja | Matrix met tekenreeksen | De lijst met opgeslagen query's.
Tables | Ja | Matrix met tekenreeksen | De lijst met opgeslagen query's.
XConnection | Ja | XConnection | Het UNO-object dat de huidige databaseverbinding vertegenwoordigt.
XMetaData | Ja | XDatabaseMetaData | Het UNO-object dat de metagegevens vertegenwoordigt die de kenmerken van het databasesysteem beschrijven.

Lijst met methodes in de databaseservice
CloseDatabase Commit CreateDataset DAvg DCount DMin | DMax DSum DLookup GetRows OpenFormDocument OpenQuery | OpenSql OpenTable Rollback RunSql SetTransactionMode

## CloseDatabase

Sluit de huidige databaseverbinding.

### Syntaxis:

db.CloseDatabase()

### Voorbeeld:

        myDatabase.CloseDatabase() ' Basic

        myDatabase.CloseDatabase() # Python

## Commit

Legt alle updates vast die zijn uitgevoerd sinds de vorige Commit- of Rollback-aanroep.

Deze methode wordt genegeerd als commits automatisch worden uitgevoerd na elke SQL-instructie, d.w.z. de database is ingesteld op de standaardmodus voor automatisch vastleggen.

### Syntaxis:

db.Commit()

### Voorbeeld:

##### In BASIC

          ' Het REPEATABLE_READ transaction-niveau instellen
          myDB.SetTransactionMode(4)
          myDB.RunSql("UPDATE ...")
          myDB.Commit()
          myDB.RunSql("DELETE ...")
          ' Test een voorwaarde voordat je een verbintenis aangaat
          If bSomeCondition Then
              myDB.Commit()
          Else
              myDB.Rollback()
          End If
          ' Herstel de automatische vastleggingsmodus
          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

Creëert een Dataset service-instantie op basis van een tabel, query of SQL SELECT-instructie.

### Syntaxis:

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

### Parameters:

sqlcommand: een tabelnaam, een querynaam of een geldige SQL SELECT-instructie. Identificatiegegevens kunnen tussen vierkante haken worden geplaatst. Dit argument is hoofdlettergevoelig.

directsql: Stel dit argument in op True om de instructie rechtstreeks naar de database-engine te sturen zonder voorverwerking door LibreOffice (standaard = False).

filter: Specificeert de voorwaarde waaraan records moeten voldoen om te worden opgenomen in de geretourneerde dataset. Dit argument wordt uitgedrukt als een SQL WHERE-instructie zonder het trefwoord "WHERE".

orderby: specificeert de volgorde van de gegevensset als een SQL ORDER BY-instructie zonder het trefwoord "ORDER BY".

### Voorbeeld:

De volgende voorbeelden in Basic en Python retourneren een gegevensset met de records van een tabel met de naam "Klanten".

##### In BASIC

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

##### In Python

          dataset = myDatabase.CreateDataset("Klanten", Filter = "[Naam] LIKE 'A'")

## DAvg, DCount, DMin, DMax, DSum

Berekent de gegeven aggregatiefunctie voor een veld of expressie die bij een tabel hoort.

Optioneel kan een SQL WHERE-clausule worden opgegeven als een filter dat wordt toegepast voorafgaand aan de aggregatiefunctie.

### Syntaxis:

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

### Parameters:

expression: Een SQL-expressie waarin de veldnamen tussen vierkante haken staan.

tablename: Een tabelnaam (zonder vierkante haken).

criterium: Een WHERE-clausule zonder het trefwoord "WHERE", waarin veldnamen tussen vierkante haken staan.

### Voorbeeld:

In het onderstaande voorbeeld wordt ervan uitgegaan dat het bestand Employees.odb een tabel heeft met de naam EmployeeData.

##### In BASIC

          GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
          Dim myDB as Variant
          Set myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")
          ' Telt het aantal medewerkers in de tabel
          MsgBox myDB.DCount("[ID]", "EmployeeData")
          ' Retourneert de som van alle salarissen in de tabel
          MsgBox myDB.DSum("[Salary]", "EmployeeData")
          ' Hieronder staan enkele voorbeelden van hoe tabellen kunnen worden gefilterd
          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

Berekent een SQL-expressie op een enkele record die wordt geretourneerd door een WHERE-clausule gedefinieerd door de parameter Criteria.

Als de query meerdere records retourneert, wordt alleen de eerste in aanmerking genomen. Gebruik de parameter OrderClause om te bepalen hoe zoekopdrachtresultaten worden gesorteerd.

### Syntaxis:

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

### Parameters:

expression: Een SQL-expressie waarin de veldnamen tussen vierkante haken staan.

tablename: Een tabelnaam (zonder vierkante haken).

criterium: Een WHERE-clausule zonder het trefwoord "WHERE", waarin veldnamen tussen vierkante haken staan.

orderclause: Een ORDER BY-clausule zonder de trefwoorden "ORDER BY". Veldnamen moeten tussen vierkante haken staan.

### Voorbeeld:

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

Slaat de inhoud van een tabel of de resultaten van een SELECT-query of van een SQL-instructie op in een tweedimensionale matrix. De eerste index in de matrix komt overeen met de rijen en de tweede index verwijst naar de kolommen.

Er kan een bovengrens worden opgegeven voor het aantal geretourneerde rijen. Optioneel kunnen kolomnamen worden ingevoegd in de eerste rij van de matrix.

De geretourneerde matrix is leeg als er geen rijen worden geretourneerd en de kolomkoppen niet vereist zijn.

### Syntaxis:

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

### Parameters:

sqlcommand: Een tabel- of querynaam (zonder vierkante haken) of een SELECT SQL-instructie.

directsql: Wanneer True, wordt de SQL-opdracht zonder voorafgaande analyse naar de database-engine gestuurd. Standaard is False. Dit argument wordt genegeerd voor tabellen. Voor query's is de toegepaste optie de optie die is ingesteld toen de query werd gedefinieerd.

header: Indien True, bevat de eerste rij van de geretourneerde matrix de kolomkoppen.

maxrows: Het maximum aantal rijen dat moet worden geretourneerd. De standaardwaarde is nul, wat betekent dat er geen limiet is aan het aantal geretourneerde rijen.

### Voorbeeld:

Hieronder staan een paar voorbeelden van hoe de methode GetRows kan worden gebruikt:

##### In BASIC

          Dim queryResults as Variant
          ' Retourneert alle rijen in de tabel met kolomkoppen
          queryResults = myDB.GetRows("EmployeeData", Header := True)
          ' Retourneert de eerste 50 werknemersrecords gerangschikt op het veld 'Voornaam'
          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

Opent het opgegeven formulierdocument in de normale modus. Deze methode retourneert een service-instantie FormDocument die overeenkomt met het opgegeven formulierdocument.

Als het formulierdocument al geopend is, wordt het formulierdocumentvenster geactiveerd.

Als het opgegeven formulierdocument niet bestaat, wordt Niets geretourneerd.

### Syntaxis:

svc.OpenFormDocument(formdocument: str): svc

### Parameters:

formdocument: De naam van het te openen FormDocument, als een hoofdlettergevoelige tekenreeks.

### Voorbeeld:

##### In BASIC

De meeste formulierdocumenten worden opgeslagen in de hoofdmap van het basisdocument en kunnen eenvoudig worden geopend met behulp van hun naam, zoals in het onderstaande voorbeeld:

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

Als formulierdocumenten in mappen zijn georganiseerd, is het noodzakelijk om de mapnaam op te nemen om aan te geven welk formulierdocument moet worden geopend, zoals geïllustreerd in het volgende voorbeeld:

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

##### In Python

        formDoc = myDB.OpenFormDocument("myFormDocument")

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

## OpenQuery

Opent het venster Gegevensweergave van de opgegeven query en retourneert een exemplaar van de Datasheet-service.

Als de query niet kon worden geopend, wordt Nothing geretourneerd.

### Syntaxis:

db.OpenQuery(queryname: str): obj

### Parameters:

queryname: De naam van een bestaande query als een hoofdlettergevoelige tekenreeks.

### Voorbeeld:

##### In BASIC

          myDatabase.OpenQuery("MyQuery")

##### In Python

          myDatabase.OpenQuery("MyQuery")

## OpenSql

Voert een SQL-opdracht SELECT uit, opent een venster Gegevensweergave met de resultaten en retourneert een instantie van de Datasheet-service.

### Syntaxis:

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

### Parameters:

sql: Een tekenreeks met een geldige SQL SELECT-instructie. Identifiers kunnen worden omsloten door vierkante haken.

directsql: Wanneer True, wordt de SQL-opdracht zonder voorafgaande analyse naar de database-engine gestuurd (standaard = False).

### Voorbeeld:

##### In BASIC

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

##### In Python

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

## OpenTable

Opent het venster Gegevensweergave van de gespecificeerde tabel en retourneert een instantie van de Datasheet-service.

### Syntaxis:

db.OpenTable(tablename: str): obj

### Parameters:

tablename: De naam van een bestaande tabel als een hoofdlettergevoelige tekenreeks.

### Voorbeeld:

##### In BASIC

          myDatabase.OpenTable("MyTable")

##### In Python

          myDatabase.OpenTable("MyTable")

## Rollback

Annuleert alle wijzigingen die in de database zijn aangebracht sinds de laatste aanroep van Commit of Rollback.

### Syntaxis:

db.Rollback()

### Voorbeeld:

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

Voert een actiequery uit van een SQL-instructie, zoals het maken van een tabel, evenals het invoegen, bijwerken en verwijderen van records.

De methode retourneert True wanneer succesvol.

De methode RunSql wordt afgewezen met een foutmelding als de database eerder in alleen-lezen modus is geopend.

### Syntaxis:

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

### Parameters:

sqlcommand: Een querynaam (zonder vierkante haken) of een SQL-instructie.

directsql: Wanneer True, wordt de SQL-opdracht zonder voorafgaande analyse naar de database-engine gestuurd. (Standaard = False). Voor query's is de toegepaste optie de optie die is ingesteld toen de query werd gedefinieerd.

### Voorbeeld:

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

Definieert het isolatieniveau bij databasetransacties.

Standaard beheren databases transacties in de auto-commit-modus, wat betekent dat er automatisch een Commit wordt uitgevoerd na elke SQL-instructie.

Gebruik deze methode om het isolatieniveau van transacties handmatig te bepalen. Wanneer een andere transactiemodus dan NONE is ingesteld, moet het script expliciet de methode Commit aanroepen om de wijzigingen op de database toe te passen.

Deze methode retourneert True als deze succesvol is.

Als u de transactiemodus wijzigt, worden alle Dataset-instanties gesloten die zijn gemaakt op basis van de huidige database.

### Syntaxis:

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

### Parameters:

transactionmode: Specificeert de transactiemodus. Dit argument moet een van de constanten zijn die zijn gedefinieerd in com.sun.star.sdbc.TransactionIsolation (Standaard = NONE)

Lees de sectie Transactieafhandeling hierboven voor meer informatie over de transactie-isolatieniveaus die worden gebruikt in LibreOffice.

### Voorbeeld:

##### In BASIC

          myDB.SetTransactionMode(com.sun.star.sdbc.TransactionIsolation.REPEATABLE_READ)
          oDataset = myDB.CreateDataset("SELECT ...")
          ' ...
          ' Zet de transactiemodus terug naar de standaardwaarde
          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-routines of variabelen die beginnen met een underscore "_" zijn voor intern gebruik. Gebruik deze niet in een Basic of Python-macro.

Verwante onderwerpen

SFDatabases.Datasheet-service

SFDatabases.Dataset-service

SFDocuments.Document-service

SFDocuments.Form-service

Service ScriptForge.UI