Innhald

# Tenesta SFDatabases.Database

Tenesta Database gjev tilgang til databasar anten innebygde eller omtalte i Base-dokument. Denne tenesta leverer metodar til:

- Få tilgang til data i databasetabellar

- Køyr SELECT-spørjingar og utfør SAMANDRAG-funksjonar.

- Køyr SQL-handlingsuttrykk som INSERT (set inn), UPDATE (oppdater), DELETE (slett) og så vidare.

Kvart eksemplar av tenesta Database representerer ein enkelt database og gjev tilgang til tabellane, spørjingane og dataa i databasen.

Denne tenesta gjev ikkje tilgang til skjema eller rapportar i Base-dokumentet som inneheld databasen. For å få tilgang til eit Base-dokument, sjå metoden FormDocuments i tenesta Base.

Alle utvekslingar mellom denne tenesta og databasen vert gjort berre ved hjelp av SQL.

SQL-uttrykk kan køyrast i direct (direkte) eller indirect (indirekte) modus. I direkte tilstand vert uttrykket overført til databasemotoren utan kontroll av syntaksen eller gjennomsyn.

Grensesnitta som føljer med, inkluderer enkle tabellar og spørjingar i tillegg til tilgang til databasedata.

For å gjera SQL-setningar enklare å lesa, kan du bruka hakeparentesar «[ ]» rundt namn på tabellar, spørjingar og felt i staden for å bruka andre omsluttande teikn som kan vera spesifikke for visse Relational Database Management Systems (RDBMS). Men merk at omsluttande teikn er obligatorisk i denne samanhengen.

## Handsaming av transaksjonar

Som standard handsamar databasen transaksjonar i auto-commit-modus, noko som betyr at ein commit vert utført etter kvar SQL-setning.

Bruk netoden SetTransactionMode for å endra standardoppførsla som tillet manuelle commit og rollback.

Metodane Commit og Rollback vert brukte for å avgrensa transaksjonane.

I LibreOffice er det fem typar transaksjonsmodus slik som definert i com.sun.star.sdbc.TransactionIsolation konstantgruppe:

Konstant | Verdi | Fortolking
--- | --- | ---
NONE | 0 | Transaksjonshandsaminga er slått av og databasen er sett til standardmodus for automatisk bekrefting.
READ_UNCOMMITTED | 1 | Ikkje-overgjevne data, ikkje-repeterbare lesingar og fantomlesingar kan finnast Viss ei rad vert endra av ein transaksjon, vil ein annan transaksjon kunna lesa desse endringane sjølv om dei ikkje er utførte.
READ_COMMITTED | 2 | Ikkje-overgjevne data vert hindra, men ikkje repeterbare data og fantomdata kan finnast. Dette nivået hindrar at rader med ubekreft endringar vert lesne.
REPEATABLE_READ | 4 | Både Ikkje-overgjevne data og repeterbare lesingar er hindra. Det kan likevel finnast fantomlesingar. I tillegg til å hindra at ikkje-bekrefta data vert lesne, hindrer det også at to leseoperasjonar i same transaksjon returnerer ulike resultat.
SERIALIZABLE | 8 | Ikkje-overgjevne data, ikkje-repeterbare lesingar og fantomlesingar er hindra. I tillegg til avgrensingane på det førre nivået, sikrar det også at settet med postar som samsvarar med eit WHERE-uttrykk ikkje vert endra i den same transaksjonen.

Les Wikipedia-sida Isolation in Database Systems for å læra meir om transaksjonsintegritet.

## Oppkall av tenester

Før du brukar tenesta Database må biblioteket ScriptForge vera lasta inn eller importert:

• Grunnleggjande makroar krev innlasting av biblioteket ScriptForge ved hjelp av denne setninga:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python-skript krev import frå scriptforge-modulen:
from scriptforge import CreateScriptService

### Syntaks:

For å laga eit eksemplar av tenesta Database kan du bruka metoden CreateScriptService:

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

I syntaksen omtalt ovanfor, kan du bruka anten «SFDatabases.Database» eller ganske enkelt «Database» som det første argumentet i metoden CreateScriptService.

### Parametrar:

filnamn: Namnet på Base-fila. Må uttrykkjast ved hjelp av SF_FileSystem.FileNaming-notasjon.

registreringsnamn: Namnet på ein registrert database. Dette argumentet bør ikkje brukast viss det er gjeve eit filnamn.

Omvend, viss det er gjeve eit registreringsnamn, bør ikkje parameteren filnamn definerast.

skriveverna: Bestemmer om databasen skal opnast som skriveverna. (Standard = Sann).

brukar, passord: Fleire tilkoplingsparameter til databasetenaren.

### Eksempel:

##### I Basic

          GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
          Dim myDatabase as Object
          Set myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
          ' Køyr spørjingar, SQL-uttrykk, …
          myDatabase.CloseDatabase()

##### I Python

          from scriptforge import CreateScriptService
          myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
          # Køyr spørjingar, SQL-uttrykk, …
          myDatabase.CloseDatabase()

## Tilgang til databasen med tenesta UI

Det er også råd å få tilgang til databasen som er knytt til eit Base-dokument ved hjelp av tenesta ScriptForge.UI som vist i eksempelet nedanfor:

##### 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")
          ' Brukar og passord vert oppgjeve nedanfor om nødvendig
          Set myDatabase = myDoc.GetDatabase()
          ' Køyr spørjingar, SQL-uttrykk, …
          myDatabase.CloseDatabase()
          myDoc.CloseDocument()

##### I Python

          ui = CreateScriptService("UI")
          doc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
          ' Brukar og passord vert oppgjeve nedanfor om nødvendig
          myDatabase = doc.GetDatabase()
          # Køyr spørjingar, SQL-uttrykk, …
          myDatabase.CloseDatabase()
          doc.CloseDocument()

GetDatabase-metoden brukt i eksempelet ovanfor er ein del av ScriptForge si Base-teneste.

## Eigenskapar

Namn | Skriveverna | Type | Beskriving
--- | --- | --- | ---
Queries | Ja | Matrise av strengar | Lista over lagra spørjingar.
Tables | Ja | Matrise av strengar | Lista over lagra tabellar.
XConnection | Ja | XConnection | UNO-objektet som representerer den gjeldande databasekoplinga.
XMetaData | Ja | XDatabaseMetaData | UNO-objektet som representerer metadataa som forklarer attributta for databasesystemet.

Liste over metodar i tenesta database
CloseDatabase Commit CreateDataset DAvg DCount DMin | DMax DSum DLookup GetRows OpenFormDocument OpenQuery | OpenSql OpenTable Rollback RunSql SetTransactionMode

## CloseDatabase

Lukkar den gjeldande databasekoplinga.

### Syntaks:

db.CloseDatabase()

### Eksempel:

        myDatabase.CloseDatabase() ' Basic

        myDatabase.CloseDatabase() # Python

## Commit

Utfører alle oppdateringar som er gjort sidan førre oppkall av Commit eller Rollback.

Denne metoden vert ignorert viss utføringar vert gjort automatisk etter kvar SQL-setning, det vil seia at databasen er sett til standard auto-commit-modus.

### Syntaks:

db.Commit()

### Eksempel:

##### I Basic

          ' Set REPEATABLE_READ transaksjonsnivået
          myDB.SetTransactionMode(4)
          myDB.RunSql("UPDATE ...")
          myDB.Commit()
          myDB.RunSql("DELETE ...")
          ' Testar nokre vilkår før utføringa
          If bSomeCondition Then
              myDB.Commit()
          Else
              myDB.Rollback()
          End If
          ' Tilbakestiller 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

Opprettar ei Dataset-teneste basert på ein tabell, ei spørjing eller eit SQL SELECT-uttrykk.

### Syntaks:

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

### Parametrar:

sqlcommand: Eit namn på ein tabell eller ei spørjing eller eit gyldig SQL SELECT-uttrykk. Identifikatorer kan vera omslutta av hakeparentesar. Dette argumentet skil mellom store og små bokstavar.

directsql: Set dette argumentet til Sann for å senda uttrykket direkte til databasemotoren utan at vert handsama på førehand av LibreOffice (Standard = Usann.

filter: Spesifiserer vilkåret som postar må samsvara med for å verta tekne med i det returnerte datasettet. Dette argumentet er uttrykt som eit SQL WHERE-uttrykk utan nøkkelordet «WHERE».

orderby: Spesifiserer rekkjefølgja på datasettet som eit SQL ORDER BY-uttrykk utan nøkkelordet «ORDER BY».

### Eksempel:

Eksempla nedanfor i Basic og Python returnerer eit datasett med postane i ein tabell kalla «Kundar».

##### I Basic

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

##### I Python

          dataset = myDatabase.CreateDataset("Kundar", Filter := "[Namn] LIKE 'A'")

## DAvg, DCount, DMin, DMax, DSum

Reknar ut den gjevne samandragsfunksjonen for eit felt eller uttrykk som høyrer til ein tabell.

Ein SQL WHERE-setningsdel kan eventuelt setjast som eit filter som skal brukast før samandragsfunksjonen

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

### Parametrar:

uttrykk: Eit SQL-uttrykk der feltnamna er omgjevne av hakeparentesar.

tabellnamn: Eit tabellnamn (utan hakeparentesar).

kriteria: Ein WHERE-setning utan «WHERE»-nøkkelordet, der feltnamna er omgjevne av hakeparentesar.

### Eksempel:

Eksempelet nedanfor går ut frå at fila Employees.odb har ein tabell med namnet EmployeeData.

##### I Basic

          GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
          Dim myDB as Variant
          Set myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")
          ' Tel kor mange tilsette i tabellen
          MsgBox myDB.DCount("[ID]", "EmployeeData")
          ' Returnerer summen av alle lønningane i tabellen
          MsgBox myDB.DSum("[Salary]", "EmployeeData")
          ' Nedanfor vert det vist nokre eksempel på filtrering av tabellar
          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

Reknar ut eit SQL-uttrykk på ein enkelt post som vert returnert av ein WHERE-setning definert av parameteren Kriterium.

Viss spørjinga returnerer fleire postar, vert berre den første rekna med. Bruk parameterenOrderClause til å bestemma korleis spørjingsresultata skal sorterast.

### Syntaks:

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

### Parametrar:

uttrykk: Eit SQL-uttrykk der feltnamna er omgjevne av hakeparentesar.

tabellnamn: Eit tabellnamn (utan hakeparentesar).

kriteria: Ein WHERE-setning utan «WHERE»-nøkkelordet, der feltnamna er omgjevne av hakeparentesar.

ordeclause: Ein ORDER BY-setning utan nøkkelorda «ORDER BY». Feltnamn må vera omgjevne av hakeparentesar.

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

Lagrar innhaldet i ein tabell eller resultatet av ei SELECT-spørjing eller av eit SQL-uttrykk i ei todimensjonal matrise. Den første indeksen i matrisa svarar til radene og den andre indeksen til kolonnane.

Du kan setja ei øvre grense for kor mange rader som skal returnerast. Kolonnenamn kan eventuelt setjast inn i den første rada i matrisa.

Den returnerte matrisa vil vera tom viss det ikkje vert returnert rader og det ikkje krevst kolonneoverskrifter.

### Syntaks:

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

### Parametrar:

sqlkommando: Eit tabell- eller spørjingsnamn (utan hakeparentesar) eller eit SELECT SQL-uytrykk.

direkte_sql: Når denne er Sann, vert SQL-kommandoen sendt til databasemotoren utan førehandsanalyse. Standard er Usann. Argumentet vert ignorert for tabellar. For spørjingar er det brukte alternativet det som vart sett då spørjinga vart definert.

header (overskrift): Når denne er Sann inneheld den første rada i den returnerte matrisa kolonneoverskriftene.

maxrows (maks-rader): Det høgaste talet på rader som kan returnerast. Standard er null, som tyder at det er inga grense for kor mange rader som kan returnerast.

### Eksempel:

Nedføre er det nokre eksempel på korleis metoden GetRows kan brukast:

##### I Basic

          Dim queryResults as Variant
          ' Returnerer alle radene i tabellen med kolonneoverskrifter
          queryResults = myDB.GetRows("EmployeeData", Header := True)
          ' Returnerer dei første 50 tilsettepostane sortert etter feltet «Fornamn»
          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

Opnar det spesifiserte skjemadokumentet i normalmodus. Denne metoden returnerer ein FormDocument-tenesteførekomst som svarar til det gjevne skjemadokumentet.

Viss skjemadokumentet alt er ope, vert vindauget for skjemadokument opna.

Viss det spesifiserte skjemadokumentet ikkje finst, vert det returrnert Ingenting.

### Syntaks:

svc.OpenFormDocument(formdocument: str): svc

### Parametrar:

skjemadokument: Namnet på eit Skjemadokument som skal opnast som ein streng som skil mellom små og store bokstavar.

### Eksempel:

##### I Basic

Dei fleste skjemadokumenta er lagra i rota til Base-dokumentet og kan opanast ved å bruka namnet, som i eksempelet nedanfor:

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

Viss skjemadokumenta er organiserte i mapper, er det nødvendig å ta med mappenamnet for å spesifisera kva skjemadokument som skal opnast. Dette er vist i det neste eksempelet:

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

##### I Python

        formDoc = myDB.OpenFormDocument("myFormDocument")

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

## OpenQuery

Opnar datavisingsvindauget for den spesifiserte spørjinga og returnerer ein førekomst av tenesta Datasheet.

Viss spørjinga ikkje kunne opnast, vert Nothing returnert.

### Syntaks:

db.OpenQuery(queryname: str): obj

### Parametrar:

queryname: Namnet på ei spørjing som finst som ein streng som skil mellom store og små bokstavar.

### Eksempel:

##### I Basic

          myDatabase.OpenQuery("MyQuery")

##### I Python

          myDatabase.OpenQuery("MyQuery")

## OpenSql

Køyrer ein SQL SELECT-kommando, opnar eit datavisings-vindauge med resultata og returnerer ein førekomst av tenseta Datasheet.

### Syntaks:

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

### Parametrar:

sql: Ein streng som inneheld ein gyldig SQL SELECT-setning. Identifikatorane kan vera omslutta av hakeparentesar.

directsql: Når Sann,vert SQL-kommandoen sendt til databasemotoren utan førehandsanalyse (Standard = Usann).

### Eksempel:

##### I Basic

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

##### I Python

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

## OpenTable

Opnar datavisings-vindauget for den gjevne tabellen og returnerer ein førekomst av Datasheet-tenesta.

### Syntaks:

db.OpenTable(tablename: str): obj

### Parametrar:

tablename: Namnet på ein tabell som finst som ein streng som skil mellom store og små bokstavar.

### Eksempel:

##### I Basic

          myDatabase.OpenTable("MyTable")

##### I Python

          myDatabase.OpenTable("MyTable")

## Rollback

Avbryt alle endringar som er gjort i databasen sidan siste oppkall til Commit eller Rollback.

### 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 ei handlingsspørjing for ei SQL-setning, for eksempel oppretting av ein tabell, i tillegg til å setja inn, oppdatera og sletta postar.

Metoden returnerer Sann når han lukkast.

Metoden RunSql vert avvist med ei feilmelding dersom databasen tidlegare vart opna som skriveverna.

### Syntaks:

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

### Parametrar:

sqlkommando: Eit spørjingsnamn (utan hakeparentesar) eller eit SQL-uttrykk.

directsql: Når denne er Sann, vert SQL-kommandoen sendt til databasemotoren utan førehandsanalyse. (Standard er Usann). For spørjingar er det brukte alternativet det som vart sett då spørjinga vart 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 databasetransaksjonar.

Som standard administrerer databasar transaksjonar i auto-commit-modus, noko som betyr at ein Commit vert utført automatisk etter kvart SQL-uttrykk.

Bruk denne metoden for å bestemma isolasjonsnivået for transaksjonar manuelt. Når ein annan transaksjonsmodus enn NONE er sett, må skriptet eksplisitt kalla opp metoden Commit for å bruka endringane i databasen.

Denne metoden returnerer Sann viss han lukkast.

Viss du endrar transaksjonsmodus, vert alle førekomster av Datasett som er oppretta frå den gjeldande databasen lukka.

### Syntaks:

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

### Parametrar:

transactionmode: Spesifiserer transaksjonsmodusen. Dette argumentet må vera ein av konstantane definert i com.sun.star.sdbc.TransactionIsolation (Standard = NONE).

Les bolken Transaksjonshandsaming ovanfor for å læra meir om transaksjonisolasjonsnivå brukte i LibreOffice.

### Eksempel:

##### I Basic

          myDB.SetTransactionMode(com.sun.star.sdbc.TransactionIsolation.REPEATABLE_READ)
          oDataset = myDB.CreateDataset("SELECT ...")
          ' ...
          ' Tilbakestiller transaksjonsmodus 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 Basic-rutinane og -identifikatorane som vert innleidde med understrek «_» er reserverte for internt bruk. Dei er ikkje meint brukte i Basic-makroar.

Liknande emne

SFDatabaser.Datasheet-teneste

SFDatabases.Dataset-tenesta

Tenesta SFDocuments.Document

Tenesta SFDocuments. Form

Tenesta ScriptForge.UI