Tjenesten SFDatabases.Database

Tjenesten Database giver adgang til databaser enten indlejrede eller beskrevet i Base-dokumenter. Denne tjeneste leverer metoder til:

Få adgang til data i databasetabeller
Kør SELECT (udvælg) forespørgsler og foretag AGGREGER-funktioner.
Kør SQL-handlingsudtryk såsom INSERT (indsæt), UPDATE (opdater), DELETE (slet) og så videre.

Hvert eksemplar af tjenesten Database repræsenterer en enkelt database og giver adgang til sine tabeller, forespørgsler og data.

Denne tjeneste giver ikke adgang til formularer eller rapporter i det Base-dokument, der indeholder databasen. For at tilgå formularer i et Base-dokument, se metoden FormDocuments (formulardokumenter) i tjenesten Base.

Alle udvekslinger mellem denne tjeneste og databaser udføres udelukkende med SQL.

SQL-udtryk kan udføres i direct (direkte) eller indirect (indirekte) tilstand. I direkte tilstand overføres udtrykket til databasemotoren uden noget syntaks-tjek eller -gennemsyn.

De leverede brugerflader inkluderer tabel- og forespørgsels-lister så vel som adgang til databasens data.

For at gøre SQL-udtryk mere læselige kan du bruge klammer "[ ]" til at omslutte navne på tabeller, forespørgsler og felter i stedet for at bruge andre omsluttende tegn, der kan være specifikke for bestemte Relational Database Management Systems (RDBMS). Men bemærk, at omsluttende tegn er obligatoriske i denne sammenhæng.

Håndtering af transaktioner

Som standard håndteringer databasen transaktioner i auto-commit-tilstand, hvilket betyder at en commit (en forpligtende ændring af data) bliver udført efter hver SQL-sætning.

Brug metoden SetTransactionMode for at ændret på standardopførslen, hvilket giver mulighed for manuelle commits og tilbagerulninger (rollbacks).

Metoderne Commit og Rollback bruges til at afgrænse transaktioner.

I LibreOffice er der fem typer transaktions-isolations-tilstande, som defineret i konstantgruppen com.sun.star.sdbc.TransactionIsolation:

Konstant	Værdi	Fortolkning
NONE	0	Transaktionshåndtering er slået fra, og databasen er sat til standardtilstanden auto-commit.
READ_UNCOMMITTED	1	Ikke-skrevne læsninger ("dirty reads"), ikke-repeterbare læsninger, og fantomlæsninger kan forekomme. Hvis en række bliver ændret af en transaktion, vil en anden transaktion være i stand til læse disse ændringer, selv hvis det ikke er blevet committede (skrevne).
READ_COMMITTED	2	Ikke-skrevne læsninger ("dirty reads") forhindres, men ikke-repeterbare læsninger og fantomlæsninger kan forekomme. Dette niveau forhindrer at rækker med ikke-committede (ikke-skrevne) ændringer bliver læst.
REPEATABLE_READ	4	Ikke-skrevne læsninger ("dirty reads") og ikke-repeterbare læsninger forhindres. Imidlertid kan fantomlæsninger forekomme. Foruden at forhindre ikke-skrevne (ikke-committede) data fra at blive læst, forhindrer det også at to læse-operationer i samme transaktion returnerer forskellige resultater.
SERIALIZABLE	8	Ikke-skrevne læsninger ("dirty reads"), ikke-repeterbare læsninger og fantomlæsninger er forhindrede. Ud over begrænsninger fra det forrige niveau, sikrer denne tilstand også at sættet af poster, der matcher en WHERE-sætning, forbliver uændret indenfor samme transaktion.

Læs Wikipedia-siden Isolation in Database Systems for at lære mere om transaktions-integritet.

Kald af tjeneste

Før brug af tjenesten Database skal biblioteket ScriptForge være indlæst eller importeret:

• Basic-makroer kræver, at biblioteket ScriptForge indlæses med følgende udtryk:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python-scripts kræver import af scriptforge-modulet:
from scriptforge import CreateScriptService

Syntaks:

For at oprette et eksemplar af tjenesten Database kan du bruge metoden CreateScriptService:

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

I den syntaks, der er beskrevet ovenfor kan du bruge enten "SFDatabases.Database" eller simpelthen "Database" som det første argument i metoden CreateScriptService.

Parametre:

filnavn: Navnet på Base-filen. Skal udtrykkes med notationen SF_FileSystem.FileNaming.

registernavn: Navnet på dem registrerede database. Hvis der opgives et filnavn, bør dette argument ikke bruges.

Omvendt, hvis der er angivet registreringsnavn, bør parameteren filnavn ikke defineres.

skrivebeskyttet: Bestemmer, om databasen skal åbnes som skrivebeskyttet (standard = True (sand)).

bruger, adgangskode: Yderligere forbindelsesparametre til databaseserveren.

Eksempel:

I Basic


      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDatabase as Object
      Set myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      ' Kør forespørgsler, SQL-udtryk, ...
      myDatabase.CloseDatabase()

I Python


      from scriptforge import CreateScriptService
      myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      # Kør forespørgsler, SQL-udtryk, ...
      myDatabase.CloseDatabase()

Tilgang til databaser med tjenesten UI

Det er også muligt at tilgå databasen, der er knyttet til et Base-dokument med tjenesten ScriptForge.UI, som vist i eksemplerne herunder:

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")
      ' Bruger og adgangskode opgives, om nødvendigt, herunder
      Set myDatabase = myDoc.GetDatabase()
      ' Kør forespørgsler, SQL-udtryk, ...
      myDatabase.CloseDatabase()
      myDoc.CloseDocument()

I Python


      ui = CreateScriptService("UI")
      doc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      # Bruger og adgangskode er anført herunder, hvis nødvendigt
      myDatabase = doc.GetDatabase()
      # Kør forespørgsler, SQL-udtryk, ...
      myDatabase.CloseDatabase()
      doc.CloseDocument()

Metoden GetDatabase (Hent_database), der er brugt i eksemplet ovenfor er en del af ScriptForge's tjeneste Base.

Egenskaber

Navn	Readonly (skrivebeskyttet)	Type (type)	Description (beskrivelse)
Queries	Yes (ja)	Array of strings (matrix af strenge)	Listen over gemte forespørgsler.
Tables	Yes (ja)	Array of strings (matrix af strenge)	Listen over gemte tabeller.
XConnection	Yes (ja)	XConnection	UNO-objektet, der repræsenterer den aktuelle dataforbindelse.
XMetaData	Yes (ja)	XDatabaseMetaData	UNO-objektet, der repræsenterer de metadata, der beskriver databasens systemattributter.

Liste over metoder i tjenesten Database
CloseDatabase Commit CreateDataset DAvg DCount DMin	DMax DSum DLookup GetRows OpenFormDocument OpenQuery	OpenSql OpenTable Rollback RunSql SetTransactionMode

CloseDatabase

Lukker den aktuelle database-forbindelse.

Syntaks:

db.CloseDatabase()

Eksempel:


    myDatabase.CloseDatabase() ' Basic


    myDatabase.CloseDatabase() # Python

Commit

Skriver (committer) alle opdateringer siden det forrige kald af Commit eller Rollback.

Denne metode ignoreres hvis commits udføres automatisk efter hver SQL-sætning, dvs. hvis databasen er sat til standardindstillingen auto-commit.

Syntaks:

db.Commit()

Eksempel:

I Basic


      ' Sæt transaktionsniveau til REPEATABLE_READ
      myDB.SetTransactionMode(4)
      myDB.RunSql("UPDATE ...")
      myDB.Commit()
      myDB.RunSql("DELETE ...")
      ' Test en betingelse før comitting (skrivning af data)
      If bSomeCondition Then
          myDB.Commit()
      Else
          myDB.Rollback()
      End If
      ' Indstil igen auto-commit-tilstand
      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

Opretter en instans af Dataset-tjenesten baseret på en tabel, en forespørgsel eller et SQL SELECT-udtryk.

Syntaks:

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

Parametre:

sqlcommand: Et tabelnavn, et forespørgselsnavn eller et gyldig SQL SELECTudtryk. Identifikatorer kan være omsluttet af firkantede parenteser. Dette argument skelner mellem store og små bogstaver.

directsql: Sæt dette argument til True for at sende udtrykket direkte til database-maskinen uden forhåndsbetahandling af LibreOffice (standard = False).

filter Angiver den tilstand, som poster skal matche for at blive inkluderet i det returnerede datasæt. Dette argument er udtrykt som et SQL WHERE-udtryk uden nøgleordet "WHERE".

orderby: Angiver rækkefølgen af datasættet som et ORDER BY-udtryk uden nøgleordet "ORDER BY".

Eksempel:

De følgende eksempler i Basic og Python returnerer et datasæt med poster fra en tabel navngivet "Kunder".

I Basic


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

I Python


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

DAvg, DCount, DMin, DMax, DSum

Beregner den givne aggreger-funktion på et felt eller udtryk, der hører til en tabel.

Valgfrit kan en SQL WHERE-delsætning angives som et filer, der anvendes forud for aggregerings-funktionen.

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:

udtryk: Et SQL-udtryk, hvor feltnavnene er omsluttet med kantede klammer.

tabelnavn: Et tabelnavn (uden kantede klammer).

kriterier: En WHERE-delsætning uden nøgleordet "WHERE", hvor feltnavnene er omsluttet af kantede parenteser.

Eksempel:

Eksemplet herunder antager, at filen Employees.odb (ansatte.odb) har en tabel med navnet EmployeeData (ansattes data).

I Basic


      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDB as Variant
      Set myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")
      ' Tæller antallet af ansatte i tabellen
      MsgBox myDB.DCount("[ID]", "EmployeeData")
      ' Returnerer summen af alle lønninger i tabellen
      MsgBox myDB.DSum("[Salary]", "EmployeeData")
      ' Herunder ses nogle 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-udtryk i en enkelt post, returneret af en WHERE-delsætning, defineret af parameteren Criteria (Kriterier).

Hvis forespørgslen returnerer flere poster, tages kun den første i betragtning. Brug parameteren OrderClause (rækkefølge-delsætning) for at afgøre, hvordan resultaterne af forespørgslen er sorteret.

Syntaks:

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

Parametre:

udtryk: Et SQL-udtryk, hvor feltnavnene er omsluttet af kantede klammer.

tabelnavn: Et tabelnavn (uden kantede klammer).

criteria: En WHERE-delsætning uden nøgleordet "WHERE", hvor feltnavnene er omsluttet af kantede parenteser.

orderclause: En ORDER BY-delsætning uden nøgleordene "ORDER BY" (sortér efter). Feltnavne bør omsluttes med kantede parenteser.

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

Gemmer indholdet af en tabel eller resultater af en SELECT (udvælg)-forespøgsel eller af et SQL-udtryk i en todimensionel matrix. Det første indeks i matrixen svarer til rækkerne og det andet indeks til kolonnerne.

Der kan angives en øvre grænse for antallet af returnerede rækker. Valgfrit kan kolonnenavne indsættes i matrixens første række.

Den returnerede matrix er tom, hvis ingen rækker returneres og der ikke kræves kolonneoverskrifter.

Syntaks:

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

Parametre:

sqlkommando: Et tabel- eller forespørgselsnavn (uden kantede klammer) eller en SELECT (udvælg) SQL-sætning.

direkte_sql: Når True (sand), sendes SQL-kommandoen til databasemotoren uden forhåndsanalyse. Standard er False (falsk). Dette argument ignoreres ved tabeller. Ved forespørgsler er den anvendte indstilling den, der blev sat, da forespørgslen blev oprettet.

overskrift: Når True (sand), indeholder den række i den returnerede matrix kolonneoverskrifterne.

maxrækker: Maksimum-antallet af rækker, der skal returneres. Standarden er nul, hvilket betyder, at der ikke er nogen grænse for antallet af returnerede rækker.

Eksempel:

Herunder er der nogle få eksempler på, hvordan metoden GetRows kan bruges:

I Basic


      Dim queryResults as Variant
      ' Returnerer alle rækker i tabellen med kolonneoverskrifter
      queryResults = myDB.GetRows("EmployeeData", Header := True)
      ' Returnerer de første 50 poster sorteret efter feltet 'FirstName' (fornavn)
      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

Åbner det angivne formulardokument i normaltilstand. Denne metode returnerer en instans af FormDocument-tjenesten, som svarer til det angivne formulardokument.

Hvis formulardokumentet allerede er åbnet, bliver formulardokumentvinduet aktiveret.

Hvis det angivne formulardokument ikke eksisterer, returneres Nothing.

Syntaks:

svc.OpenFormDocument(formdocument: str): svc

Parametre:

formdocument: Navnet på det FormDocument, som skal åbnes, som en streng med forskel på store og små bogstaver.

Eksempel:

I Basic

De fleste formulardokumenter er lagret i roden af Base-dokumentet, og de kan åbnes ved at bruge deres navne, som i eksemplet herunder:


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

Hvis formulardokumenter er organiserede i mapper, bliver det nødvendigt at medtage mappenavnet for at specificere det formulardokument, som skal åbnes. Dette er illustreret i det følgende eksempel:


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

I Python


    formDoc = myDB.OpenFormDocument("myFormDocument")


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

OpenQuery

Åbner datavisningsvinduet for den angivne forespørgsel, og returnerer en instans af Datasheet-tjenesten.

Hvis forespørgslen ikke kunne åbnes, returneres Nothing.

Syntaks:

db.OpenQuery(queryname: str): obj

Parametre:

queryname: Navnet på en eksisterende forespørgsel, som en streng med forskel på store og små bogstaver.

Eksempel:

I Basic


      myDatabase.OpenQuery("MyQuery")

I Python


      myDatabase.OpenQuery("MyQuery")

OpenSql

Udfører en SQL SELECT-kommando, åbner et datavisningsvindue med resultatet, og returnerer en instans af Datasheet-tjenesten.

Syntaks:

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

Parametre:

sql: En streng som indeholder et gyldigt SQL SELECT-udtryk. Identfikatorer kan være omgivet af firkantede parenteser.

directsql: Når True bliver SQL-kommandoen sendt til database-maskinen uden forhåndsanalyse (standard = False).

Eksempel:

I Basic


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

I Python


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

OpenTable

Åbner datavisnings-vinduet for den angivne tabel og returnerer en instans af Datasheet-tjenesten.

Syntaks:

db.OpenTable(tablename: str): obj

Parametre:

tablename: Navnet på en eksisterende tabel som en streng, med forskel på store og små bogstaver.

Eksempel:

I Basic


      myDatabase.OpenTable("MyTable")

I Python


      myDatabase.OpenTable("MyTable")

Rollback

Nulstiller alle ændringer lavet i databasen siden sidste kald af 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

Udfører en SQL-erklærings handlingsforespørgsel såsom at oprette en tabel, såvel som indsættelse, opdatering og sletning af poster.

Metoden returnerer True (sand), når den lykkes.

Metoden RunSql (kør SQL) forkastes med en fejlmeddelelse i det tilfælde, at databasen tidligere blev åbnet i skrivebeskyttet tilstand.

Syntaks:

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

Parametre:

sqlkommando: En forespørgselsnavn (uden kantede klammer) eller et SQL-udtryk.

direkte_sql: Når True (sand), sendes SQL-kommandoen til databasemotoren uden forhåndsanalyse. (Standard = False (falsk)). Ved forespørgsler er den anvendte indstilling den, der blev sat, da forespørgslen blev oprettet.

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 isolationsniveauet i databasetransaktioner.

Som standard administrerer databaser transaktioner i "auto-commit"-tilstand, hvilket betyder at en Commit automatisk udføres efter hver SQL-kommando.

Brug denne metode til manuelt at bestemme isolationsniveauet for transaktioner. Når en anden transaktionstilstand end NONE er sat, så er scriptet nødt til eksplicit at kalde Commit-metoden for at anvende ændringerne på databasen.

Denne metode returnerer True (sand), når den lykkes.

Ved ændring af transaktionstilstand lukkes alle Dataset-instanser, som er oprettet fra den aktuelle database.

Syntaks:

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

Parametre:

transactionmode: Angiver transaktions-tilstand. Dette argument skal være en af konstanterne defineret i com.sun.star.sdbc.TransactionIsolation (standard = NONE).

Læs afsnittet Transaktionshåndtering ovenfor for at lære mere om de transaktions-isolationsniveauer, som bruges i LibreOffice.

Eksempel:

I Basic


      myDB.SetTransactionMode(com.sun.star.sdbc.TransactionIsolation.REPEATABLE_READ)
      oDataset = myDB.CreateDataset("SELECT ...")
      ' ...
      ' Nulstil transaktionstilstand 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-rutiner eller identifikatorer, der indledes med et understregstegn "_" er reserveret til internt brug. Det er ikke meningen, at de skal bruges i Basic-makroer eller Python-scripts.

SFDatabases.Datasheet-tjeneste

SFDatabases.Dataset-tjeneste

Tjenesten SFDocuments.Document

Tjenesten SFDocuments.Form

Tjenesten ScriptForge.UI (brugerflade)