SFDatabaser.Database-tjeneste

Tjenesten Database gir tilgang til databaser enten innebygd eller beskrevet i basisdokumenter. Denne tjenesten tilbyr metoder for å:

Hver forekomst av Database-tjenesten representerer en enkelt database og gir tilgang til dens tabeller, spørringer og data.

Denne tjenesten gir ikke tilgang til skjemaer eller rapporter i basisdokumentet som inneholder databasen. For å få tilgang til skjemaer i et Base Dokument, se metoden FormDocuments av Base-tjenesten.

note

Alle utvekslinger mellom denne tjenesten og databasen gjøres kun ved hjelp av SQL.


SQL-setninger kan kjøres i direkte eller indirekte-modus. I direkte modus overføres setningen til databasemotoren uten syntakskontroll eller gjennomgang.

De medfølgende grensesnittene inkluderer enkle tabeller og spørringslister, samt tilgang til databasedata.

tip

For å gjøre SQL-setninger mer lesbare, kan du bruke hakeparenteser "[ ]" for å omslutte navn på tabeller, spørringer og felt i stedet for å bruke andre omsluttende tegn som kan være eksklusive for visse Relational Database Management Systems (RDBMS). Men pass på at vedlagte tegn er obligatorisk i denne sammenhengen.


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


tip

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


Tjenestepåkallelse

Før du bruker Database-tjenesten, må ScriptForge-biblioteket lastes eller importeres:

note

• Grunnleggende makroer krever å laste ScriptForge-biblioteket ved hjelp av følgende setning:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python-skript krever import fra scriptforge-modulen:
fra scriptforge import CreateScriptService


Syntaks:

For å opprette en forekomst av Database-tjenesten kan du bruke CreateScriptService-metoden:

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

note

I syntaksen beskrevet ovenfor kan du bruke enten "SFDatabases.Database" eller ganske enkelt "Database" som det første argumentet for CreateScriptService-metoden.


Parametre:

filnavn: Navnet på basisfilen. Må uttrykkes med SF_FileSystem.FileName notasjon.

registreringsnavn: Navnet på en registrert database. Hvis filnavn er oppgitt, bør ikke dette argumentet brukes.

Omvendt, hvis et registreringsnavn er spesifisert, bør ikke parameteren filnavn defineres.

skrivebeskyttet: Bestemmer om databasen skal åpnes som skrivebeskyttet (Standard = Sann).

bruker, passord: Ytterligere tilkoblingsparametere til databaseserveren.

Eksempel:

I Basic

      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDatabase as Object
      Set myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      ' Kjør spørringer, SQL-setninger, ...
      myDatabase.CloseDatabase()
    
I Python

      from scriptforge import CreateScriptService
      myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      # Kjør spørringer, SQL-setninger, ...
      myDatabase.CloseDatabase()
    

Tilgang til databaser med UI-tjenesten

Det er også mulig å få tilgang til databasen knyttet til et Base dokument ved å bruke ScriptForge.UI-tjenesten, som vist i eksemplene nedenfor:

I Basic

      Dim myDoc As Object, myDatabase As Object, ui As Object
      Set ui = CreateScriptService("UI")
      Set myDoc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      ' Bruker og passord er oppgitt nedenfor, hvis nødvendig
      Set myDatabase = myDoc.GetDatabase()
      ' Kjør spørringer, SQL-setninger, ...
      myDatabase.CloseDatabase()
      myDoc.CloseDocument()
    
I Python

      ui = CreateScriptService("UI")
      doc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      # Bruker og passord er oppgitt nedenfor, hvis nødvendig
      myDatabase = doc.GetDatabase()
      # Kjør spørringer, SQL-setninger, ...
      myDatabase.CloseDatabase()
      doc.CloseDocument()
    
tip

GetDatabase-metoden brukt i eksempelet ovenfor er en del av ScriptForges Base service.


Egenskaper

Navn

Skrivebeskyttet

Type

Beskrivelse

Queries

Ja

En matrise med strenger

Listen over lagrede spørringer.

Tables

Ja

En matrise med strenger

Listen over lagrede tabeller.

XConnection

Ja

XConnection

UNO-objektet som representerer gjeldende databasetilkobling.

XMetaData

Ja

XDatabaseMetaData

UNO-objektet som representerer metadataene som beskriver databasesystemattributtene.


Liste over metoder i databasetjenesten

CloseDatabase
Commit
CreateDataset
DAvg
DCount
DMin

DMax
DSum
DLookup
GetRows
OpenFormDocument
OpenQuery

OpenSql
OpenTable
Rollback
RunSql
SetTransactionMode


CloseDatabase

Lukker gjeldende databasetilkobling.

Syntaks:

db.CloseDatabase()

Eksempel:


    myDatabase.CloseDatabase() ' Basic
  

    myDatabase.CloseDatabase() # Python
  

Commit

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

note

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.


Syntaks:

db.Commit()

Eksempel:

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

Syntaks:

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

Parametre:

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

Eksempel:

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

I Basic

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

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

DAvg, DCount, DMin, DMax, DSum

Lukker gjeldende databasetilkobling.

Eventuelt kan en SQL WHERE-klausul spesifiseres som et filter som skal brukes før aggregatfunksjonen.

Syntaks:

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

Parametre:

uttrykk: Et SQL-uttrykk der feltnavnene er omgitt av hakeparenteser.

tabellnavn: Et tabellnavn (uten hakeparenteser).

kriterier: En WHERE-klausul uten nøkkelordet "WHERE", der feltnavn er omgitt av hakeparenteser.

Eksempel:

Eksemplet nedenfor antar at filen Employees.odb har en tabell kalt EmployeeData.

I Basic

      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDB as Variant
      Set myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")
      ' Teller antall ansatte i tabellen
      MsgBox myDB.DCount("[ID]", "EmployeeData")
      ' Returnerer summen av alle lønninger i tabellen
      MsgBox myDB.DSum("[Salary]", "EmployeeData")
      ' Nedenfor er noen eksempler på hvordan tabeller kan filtreres
      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%'")
    
I 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

Beregner et SQL-uttrykk på en enkelt post som returneres av en WHERE-ledd definert av parameteren Criteria.

Hvis spørringen returnerer flere poster, vurderes bare den første. Bruk parameteren OrderClause for å bestemme hvordan søkeresultatene skal sorteres.

Syntaks:

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

Parametre:

uttrykk: Et SQL-uttrykk der feltnavnene er omgitt av hakeparenteser.

tabellnavn: Et tabellnavn (uten hakeparenteser).

kriterier: En WHERE-klausul uten nøkkelordet "WHERE", der feltnavn er omgitt av hakeparenteser.

orderclausule: En ORDER BY-klausul uten "ORDER BY"-nøkkelord. Feltnavn skal være omgitt av hakeparenteser.

Eksempel:

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

Lagrer innholdet i en tabell eller resultatene av en SELECT-spørring eller av en SQL-setning i en todimensjonal matrise. Den første indeksen i matrisen tilsvarer radene og den andre indeksen refererer til kolonnene.

En øvre grense kan angis for antall returnerte rader. Eventuelt kan kolonnenavn settes inn i den første raden i matrisen.

Den returnerte matrisen vil være tom hvis ingen rader returneres og kolonneoverskriftene ikke er nødvendige.

Syntaks:

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

Parametre:

sqlcommand: Et tabell- eller spørringsnavn (uten hakeparenteser) eller en SELECT SQL-setning.

directsql: Når True, sendes SQL-kommandoen til databasemotoren uten forhåndsanalyse. Standard er Usann. Dette argumentet ignoreres for tabeller. For spørringer er det valgte alternativet det som ble angitt da spørringen ble definert.

header: Når Sann, inneholder den første raden i den returnerte matrisen kolonneoverskriftene.

maxrows: Maksimalt antall rader som skal returneres. Standarden er null, noe som betyr at det ikke er noen grense for antall returnerte rader.

Eksempel:

Nedenfor er noen eksempler på hvordan GetRows-metoden kan brukes:

I Basic

      Dim queryResults as Variant
      ' Returnerer alle rader i tabellen med kolonneoverskrifter
      queryResults = myDB.GetRows("EmployeeData", Header := True)
      ' Returnerer de første 50 ansattepostene sortert etter 'FirstName'-feltet
      queryResults = myDB.GetRows("SELECT * FROM EmployeeData ORDER BY [FirstName]", MaxRows := 50)
    
I 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.

Syntaks:

svc.OpenFormDocument(formdocument: str): svc

Parametre:

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

Eksempel:

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

    formDoc = myDB.OpenFormDocument("myFormDocument")
  

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

OpenQuery

Åpner datavisningsvinduet for den angitte spørringen og returnerer en forekomst av Dataark-tjenesten.

Hvis spørringen ikke kunne åpnes, returneres Ingenting.

Syntaks:

db.OpenQuery(queryname: str): obj

Parametre:

queryname: Navnet på en eksisterende spørring som en streng som skiller mellom store og små bokstaver.

Eksempel:

I Basic

      myDatabase.OpenQuery("MyQuery")
    
I Python

      myDatabase.OpenQuery("MyQuery")
    

OpenSql

Kjører en SQL SELECT-kommando, åpner et Datavisnings-vindu med resultatene og returnerer en forekomst av Datasheet-tjenesten.

Syntaks:

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

Parametre:

sql: En streng som inneholder en gyldig SQL SELECT-setning. Identifikatorer kan være omgitt av firkantede parenteser.

directsql: Når Sann, sendes SQL-kommandoen til databasemotoren uten forhåndsanalyse (Standard = Usann).

Eksempel:

I Basic

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

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

OpenTable

Åpner Data View-vinduet i den angitte tabellen og returnerer en forekomst av Dataark-tjenesten.

Syntaks:

db.OpenTable(tablename: str): obj

Parametre:

tabellnavn: Navnet på en eksisterende tabell som en streng som skiller mellom store og små bokstaver.

Eksempel:

I Basic

      myDatabase.OpenTable("MyTable")
    
I Python

      myDatabase.OpenTable("MyTable")
    

Rollback

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

Syntaks:

db.Rollback()

Eksempel:

I Basic

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

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

RunSql

Utfører en handlingsforespørsel for en SQL-setning, for eksempel å lage en tabell, samt sette inn, oppdatere og slette poster.

Metoden returnerer Sann når den er vellykket.

tip

RunSql-metoden avvises med en feilmelding i tilfelle databasen tidligere ble åpnet i skrivebeskyttet modus.


Syntaks:

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

Parametre:

sqlcommand: Et spørringsnavn (uten hakeparenteser) eller en SQL-setning.

directsql: Når True, sendes SQL-kommandoen til databasemotoren uten forhåndsanalyse. (Standard = False). For spørringer er det valgte alternativet det som ble angitt da spørringen ble definert.

Eksempel:

I Basic

      myDatabase.RunSql("INSERT INTO [EmployeeData] VALUES(25, 'Smith', 'John')", DirectSQL := True)
    
I 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.

warning

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


Syntaks:

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

Parametre:

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

note

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


Eksempel:

I Basic

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

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

Alle ScriptForge Grunnleggende rutiner eller identifikatorer som er prefikset med et understrekingstegn "_" er reservert for intern bruk. De er ikke ment å brukes i grunnleggende makroer eller Python-skript.