SFDatabases.Database-service

De service Database biedt toegang tot databases die zijn ingesloten of beschreven in Base-documenten. Deze service biedt methoden 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 methoden Commit en Rollback worden gebruikt om transacties af te bakenen.

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

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

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.

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.

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

      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:

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

      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

CloseDatabase

Sluit de huidige databaseverbinding.

db.CloseDatabase()

    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.

db.Commit()

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

      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.

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

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

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

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

      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.

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

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

tablename: Een tabelnaam (zonder vierkante haken).

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

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

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

      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.

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

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

tablename: Een tabelnaam (zonder vierkante haken).

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

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

      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.

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

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.

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

      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)
    

      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.

svc.OpenFormDocument(formdocument: str): svc

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

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

    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.

db.OpenQuery(queryname: str): obj

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

      myDatabase.OpenQuery("MyQuery")
    

      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.

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

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

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

      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.

db.OpenTable(tablename: str): obj

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

      myDatabase.OpenTable("MyTable")
    

      myDatabase.OpenTable("MyTable")
    

Rollback

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

db.Rollback()

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

      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.

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

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.

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

      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.

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

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.

      myDB.SetTransactionMode(com.sun.star.sdbc.TransactionIsolation.REPEATABLE_READ)
      oDataset = myDB.CreateDataset("SELECT ...")
      ' ...
      ' Zet de transactiemodus terug naar de standaardwaarde
      myDB.SetTransactionMode()
    

      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.