Tenesta SFDatabases.Database

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

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.

note

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.

tip

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 LibreOfficeDev er det fem typar transaksjonsmodus slik som definert i com.sun.star.sdbc.TransactionIsolation konstantgruppe:

Konstant

Verdi

Fortolking

INGEN

0

Transaksjonshandsaminga er slått av og databasen er sett til standardmodus for automatisk bekrefting.

READ_UNCOMMITTED

1

Dirty reads, non-repeatable reads and phantom reads can occur.

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

Dirty reads are prevented, however non-repeatable reads and phantom reads can occur.

Dette nivået hindrar at rader med ubekreft endringar vert lesne.

REPEATABLE_READ

4

Dirty reads and non-repeatable reads are prevented. However, phantom reads can occur.

I tillegg til å hindra at ikkje-bekrefta data vert lesne, hindrer det også at to leseoperasjonar i same transaksjon returnerer ulike resultat.

SERIALIZABLE

8

Dirty reads, non-repeatable reads and phantom reads are prevented.

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.


tip

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:

note

• 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

note

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.

Omvendt, 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()
    
tip

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.

note

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

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

Parametrar:

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

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øgste 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 eksisterande spørjing 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 eksisterande tabell som ein streng som skil mellom store og små bokstavar.

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

tip

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

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

Parametrar:

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 Basic-rutinane og -identifikatorane som vert innleidde med understrek «_» er reserverte for internt bruk. Dei er ikkje meint brukte i Basic-makroar.