SFDatabaser.Database-tjeneste

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

Få tilgang til data i databasetabeller.
Kjør SELECT-spørringer og utfør aggregerte funksjoner.
Kjør SQL-handlingssetninger som INSERT, UPDATE, DELETE osv.

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.

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.

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.

Transaksjonshåndtering

Som standard håndterer databasen transaksjoner i auto-commit-modus, noe som betyr at en commit utføres etter hver SQL-setning.

Bruk metoden SetTransactionMode for å endre standardoppførselen, som tillater manuelle commits og rollbacks.

Metodene Commit og Rollback brukes til å avgrense transaksjoner.

I LibreOffice er det fem typer transaksjonsisoleringsmoduser, som definert i com.sun.star.sdbc .TransactionIsolation konstant gruppe:

Konstant	Verdi	Tolkning
NONE	0	Transaksjonshåndtering er deaktivert og databasen er satt til standard auto-commit-modus.
READ_UNCOMMITTED	1	Skitne lesninger, ikke-repeterbare lesninger og fantomesninger kan forekomme. Hvis en rad endres av en transaksjon, vil en annen transaksjon kunne lese disse endringene selv om de ikke er avsluttet.
READ_COMMITTED	2	Skitne lesninger forhindres, men ikke-repeterbare lesninger og fantomlesninger kan forekomme. Dette nivået forhindrer at rader med ikke-fullførte endringer leses.
REPEATABLE_READ	4	Skitne lesninger og ikke-repeterbare lesninger forhindres. Fantomlesninger kan imidlertid forekomme. I tillegg til å forhindre at ikke-fullførte data blir lest, forhindrer det også at to leseoperasjoner i samme transaksjon gir forskjellige resultater.
SERIALIZABLE	8	Skitne lesninger, ikke-repeterbare lesninger og fantomlesninger forhindres. I tillegg til begrensningene på forrige nivå, sikrer den også at settet med poster som samsvarer med en WHERE-klausul forblir uendret i samme transaksjon.

Les Wikipedia-siden på Isolering i databasesystemer for å lære mer om transaksjonsintegritet.

Tjenestepåkallelse

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

• 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

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

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

Fullfører alle oppdateringer gjort siden forrige Fullføring eller Rulle tilbake anrop.

Denne metoden ignoreres hvis fullføring gjøres automatisk etter hver SQL-setning, dvs. databasen er satt til standard auto-fulføring-modus.

Syntaks:

db.Commit()

Eksempel:

I Basic


      ' Angi transaksjonsnivået REPEATABLE_READ
      myDB.SetTransactionMode(4)
      myDB.RunSql("UPDATE ...")
      myDB.Commit()
      myDB.RunSql("DELETE ...")
      ' Test en tilstand før fullføring
      If bSomeCondition Then
          myDB.Commit()
      Else
          myDB.Rollback()
      End If
      ' Gjenopprett auto-commit-modus
      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

Oppretter en Datasett-tjenesteforekomst basert på en tabell, spørring eller SQL SELECT-setning.

Syntaks:

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

Parametre:

sqlcommand: Et tabellnavn, et spørringsnavn eller en gyldig SQL SELECT-setning. Identifikatorer kan være omgitt av firkantede parenteser. Dette argumentet skiller mellom store og små bokstaver.

directsql: Sett dette argumentet til sann for å sende setningen direkte til databasemotoren uten forhåndsbehandling av LibreOffice (Standard = Usann).

filter: Angir betingelsen som poster må samsvare med for å bli inkludert i det returnerte datasettet. Dette argumentet er uttrykt som en SQL WHERE-setning uten nøkkelordet "WHERE".

ordreby: Spesifiserer rekkefølgen av datasettet som en SQL ORDER BY-setning uten nøkkelordet "ORDER BY".

Eksempel:

Følgende eksempler i Basic og Python returnerer et datasett med postene til en tabell kalt "Kunder".

I Basic


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

I Python


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

Åpner det angitte skjemadokumentet i normal modus. Denne metoden returnerer en FormDocument tjenesteforekomst som tilsvarer det angitte skjemadokumentet.

Hvis skjemadokumentet allerede er åpent, aktiveres skjemadokumentvinduet.

Hvis det angitte skjemadokumentet ikke eksisterer, returneres Ingenting.

Syntaks:

svc.OpenFormDocument(formdocument: str): svc

Parametre:

formdocument: Navnet på FormDocument som skal åpnes, som en streng som skiller mellom store og små bokstaver.

Eksempel:

I Basic

De fleste skjemadokumenter er lagret i roten av basisdokumentet, og de kan åpnes ved å bruke navnene deres, som i eksemplet nedenfor:


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

Hvis skjemadokumenter er organisert i mapper, blir det nødvendig å inkludere mappenavnet for å spesifisere skjemadokumentet som skal åpnes, som illustrert i følgende eksempel:


    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

Avbryter alle endringer som er gjort i databasen siden siste Commit eller Rollback anrop.

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.

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

Definerer isolasjonsnivået i databasetransaksjoner.

Som standard administrerer databaser transaksjoner i auto-commit-modus, noe som betyr at en Commit utføres automatisk etter hver SQL-setning.

Bruk denne metoden til å bestemme isolasjonsnivået for transaksjoner manuelt. Når en annen transaksjonsmodus enn NONE er satt, må skriptet eksplisitt kalle Commit-metoden for å bruke endringene på databasen.

Denne metoden returnerer True når den er vellykket.

Endring av transaksjonsmodus lukker alle Datasett-forekomster opprettet fra gjeldende database.

Syntaks:

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

Parametre:

transaksjonsmodus: Spesifiserer transaksjonsmodus. Dette argumentet må være en av konstantene som er definert i com.sun.star.sdbc.TransactionIsolation ( Standard = INGEN)

Les delen Transaksjonshåndtering ovenfor for å lære mer om transaksjonsisolasjonsnivåene som brukes i LibreOffice.

Eksempel:

I Basic


      myDB.SetTransactionMode(com.sun.star.sdbc.TransactionIsolation.REPEATABLE_READ)
      oDataset = myDB.CreateDataset("SELECT ...")
      ' ...
      ' Tilbakestill transaksjonsmodusen til standard
      myDB.SetTransactionMode()

I Python


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

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.

SFDatabaser.Dataark tjeneste

SFDatabaser.Datasett-tjeneste

SFDocuments.Dokument tjeneste

SFDocuments.Form tjeneste

ScriptForge.UI tjeneste