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.

Transaction handling

By default the database handles transactions in auto-commit mode, meaning that a commit is done after every SQL statement.

Use the SetTransactionMode method to change the default behavior, which allows for manual commits and rollbacks.

The methods Commit and Rollback are used to delimit transactions.

In LibreOffice, there are five types of transaction isolation modes, as defined in the com.sun.star.sdbc.TransactionIsolation constant group:

Constant	Value	Interpretation
NONE	0	Transaction handling is disabled and the database is set to the default auto-commit mode.
READ_UNCOMMITTED	1	Dirty reads, non-repeatable reads and phantom reads can occur. If a row is changed by a transaction, another transaction will be able to read these changes even if they have not been committed.
READ_COMMITTED	2	Dirty reads are prevented, however non-repeatable reads and phantom reads can occur. This level prevents that rows with uncommitted changes are read.
REPEATABLE_READ	4	Dirty reads and non-repeatable reads are prevented. However, phantom reads can occur. Besides preventing uncommitted data from being read, it also prevents that two read operations in the same transaction return different results.
SERIALIZABLE	8	Dirty reads, non-repeatable reads and phantom reads are prevented. In addition to the constraints of the previous level, it also ensures that the set of records that match a WHERE clause remains unchanged inside the same transaction.

Read the Wikipedia page on Isolation in Database Systems to learn more about transaction integrity.

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

Commits all updates done since the previous Commit or Rollback call.

This method is ignored if commits are done automatically after each SQL statement, i.e. the database is set to the default auto-commit mode.

Syntaks:

db.Commit()

Eksempel:

I Basic


      ' Set the REPEATABLE_READ transaction level
      myDB.SetTransactionMode(4)
      myDB.RunSql("UPDATE ...")
      myDB.Commit()
      myDB.RunSql("DELETE ...")
      ' Test some condition before committing
      If bSomeCondition Then
          myDB.Commit()
      Else
          myDB.Rollback()
      End If
      ' Restore auto-commit mode
      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

Parametre:

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

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

Valgfrit kan en SQL WHERE (hvor)-sætning angives som et filer, der anvendes forud for aggreger-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 (hvor)-sætning uden nøgleordet "WHERE", hvor feltnavnene er omsluttet af kantede klammer.

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 (hvor)-sæ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-sæ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).

kriterier: En WHERE (hvor)- sætning uden nøgleordet "WHERE", hvor feltnavnene er omsluttet af kantede klammer.

sorter-sætning: En ORDER BY (sorter efter)-sætning uden nøgleordene "ORDER BY" (sorter efter). Feltnavne bør omsluttes med kantede klammer.

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

Opens the specified form document in normal mode. This method returns a FormDocument service instance corresponding to the specified form document.

If the form document is already open, the form document window is activated.

If the specified form document does not exist, then Nothing is returned.

Syntaks:

svc.OpenFormDocument(formdocument: str): svc

Parametre:

formdocument: The name of the FormDocument to be opened, as a case-sensitive string.

Eksempel:

I Basic

Most form documents are stored in the root of the Base document and they can be opened simply using their names, as in the example below:


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

If form documents are organized in folders, it becomes necessary to include the folder name to specify the form document to be opened, as illustrated in the following example:


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

I Python


    formDoc = myDB.OpenFormDocument("myFormDocument")


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

OpenQuery

Opens the Data View window of the specified query and returns an instance of the Datasheet service.

If the query could not be opened, then Nothing is returned.

Syntaks:

db.OpenQuery(queryname: str): obj

Parametre:

queryname: The name of an existing query as a case-sensitive String.

Eksempel:

I Basic


      myDatabase.OpenQuery("MyQuery")

I Python


      myDatabase.OpenQuery("MyQuery")

OpenSql

Runs a SQL SELECT command, opens a Data View window with the results and returns an instance of the Datasheet service.

Syntaks:

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

Parametre:

sql: A string containing a valid SQL SELECT statement. Identifiers may be enclosed by square brackets.

directsql: When True, the SQL command is sent to the database engine without pre-analysis (Default = False).

Eksempel:

I Basic


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

I Python


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

OpenTable

Opens the Data View window of the specified table and returns an instance of the Datasheet service.

Syntaks:

db.OpenTable(tablename: str): obj

Parametre:

tablename: The name of an existing table as a case-sensitive String.

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

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

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.

Changing the transaction mode closes all Dataset instances created from the current database.

Syntaks:

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

Parametre:

transactionmode: Specifies the transaction mode. This argument must be one of the constants defined in com.sun.star.sdbc.TransactionIsolation (Default = NONE)

Read the section Transaction handling above to learn more about the transaction isolation levels used in LibreOffice.

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

Alle ScriptForge Basic-rutiner eller identifikatorer, der er indledet med et understreget tegn "_" er reserveret til internt brug. Det er ikke meningen, at de skal bruges i Basic-makroer eller Python-scripts.

SFDatabases.Datasheet service

SFDatabases.Dataset service

Tjenesten SFDocuments.Document

Tjenesten SFDocuments.Form

Tjenesten ScriptForge.UI (brugerflade)