SFDatabases.Database service

Innhold

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

Lignende emner

SFDatabaser.Dataark tjeneste

SFDatabaser.Datasett-tjeneste

SFDocuments.Dokument tjeneste

SFDocuments.Form tjeneste

ScriptForge.UI tjeneste

Supporter oss!