Storitev SFDatabases.Database

Storitev Database zagotavlja dostop do zbirk podatkov, ki so vdelane ali opisane v dokumentih Base. Ta storitev zagotavlja metode za:

Vsaka instanca storitve Database predstavlja posamezno zbirko podatkov in ponuja dostop do njenih tabel, poizvedb in podatkov.

Ta storitev ne ponuja dostopa do obrazcev ali poročil v dokumentih Base, ki vsebujejo zbirko podatkov. Če želite dostopati do obrazcev v dokumentu programa Base, glejte metodo FormDocuments storitve Base.

note

Vse izmenjave med to storitvijo in zbirko podatkov se izvedejo zgolj z uporabo SQL.


Izjave oz. ukaze SQL lahko izvedete neposredno ali posredno. V neposrednem načinu je izjava prenesena v pogon zbirke podatkov brez preverjanja skladnje ali pregleda.

Podani vmesniki vključujejo enostavne sezname tabel in poizvedb, kot tudi dostop do podatkov zbirke podatkov.

tip

Da bi bile izjave SQL lažje berljive, lahko uporabite neobvezne oglate oklepaje »[ ]« za podajanje imen tabel, poizvedb in polj namesto uporabe drugih znakov za navajanje, ki so morda ekskluzivni za določene sisteme upravljanja relacijskih zbirk podatkov (RDBMS). Vendar ne pozabite, da so znaki zaobjetja podatkov v tem kontekstu obvezni.


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


tip

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


Priklic storitve

Pred uporabo storitve Database je potrebno naložiti ali uvoziti knjižnico ScriptForge:

note

• Za makre Basic mora biti naložena knjižnica ScriptForge z naslednjim ukazom:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Za skripte Python mora biti opravljen uvoz iz modula scriptforge:
from scriptforge import CreateScriptService


Skladnja:

Instanco storitve Database lahko tvorite tudi z metodo CreateScriptService:

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

note

Z zgoraj opisano skladnjo lahko za prvi argument metode CreateScriptService uporabite »SFDatabases.Database« ali enostavno »Database«.


Parametri:

filename: ime datoteke programa Base. Izraženo mora biti v zapisu SF_FileSystem.FileNaming.

registrationname: ime registrirane zbirke podatkov. Če je podano ime datoteke filename, tega argumenta ne uporabljajte.

Ravno nasprotno, če je določen parameter registrationname, potem parameter filename ne sme biti določen.

readonly: določa, ali bo zbirka podatkov odprta samo za branje (privzeta vrednost je True).

user, password: parametra prijave (uporabniško ime in geslo) za strežnik zbirke podatkov.

Primer:

V Basicu

      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDatabase as Object
      Set myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      ' Izvedite poizvedbe, ukaze SQL ...
      myDatabase.CloseDatabase()
    
V Pythonu

      from scriptforge import CreateScriptService
      myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      # Izvedite poizvedbe, ukaze SQL ...
      myDatabase.CloseDatabase()
    

Dostop do zbirk podatkov s storitvijo UI

Do zbirke podatkov, povezane z dokumentom programa Base, lahko dostopate tudi s storitvijo ScriptForge.UI, kar prikazuje spodnji primeri:

V Basicu

      Dim myDoc As Object, myDatabase As Object, ui As Object
      Set ui = CreateScriptService("UI")
      Set myDoc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      ' Uporabnik in geslo sta navedena spodaj, če jih potrebujete
      Set myDatabase = myDoc.GetDatabase()
      ' Izvedite poizvedbe, ukaze SQL ...
      myDatabase.CloseDatabase()
      myDoc.CloseDocument()
    
V Pythonu

      ui = CreateScriptService("UI")
      doc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      # Uporabnik in geslo sta navedena spodaj, če jih potrebujete
      myDatabase = doc.GetDatabase()
      # Izvedite poizvedbe, ukaze SQL ...
      myDatabase.CloseDatabase()
      doc.CloseDocument()
    
tip

V zgornjem primeru uporabljena metoda GetDatabase je del storitve ScriptForge Base.


Lastnosti

Ime

Samo za branje

Vrsta

Opis

Queries

Da

Polje nizov

Seznam shranjenih poizvedb.

Tables

Da

Polje nizov

Seznam shranjenih tabel.

XConnection

Da

XConnection

Predmet UNO, ki predstavlja povezavo s trenutno zbirko podatkov.

XMetaData

Da

XDatabaseMetaData

Predmet UNO, ki predstavlja metapodatke, ki opisujejo sistemske atribute zbirke podatkov.


Seznam metod v storitvi Database

CloseDatabase
Commit
CreateDataset
DAvg
DCount
DMin

DMax
DSum
DLookup
GetRows
OpenFormDocument
OpenQuery

OpenSql
OpenTable
Rollback
RunSql
SetTransactionMode


CloseDatabase

Zapre trenutno povezavo zbirke podatkov.

Skladnja:

db.CloseDatabase()

Primer:


    myDatabase.CloseDatabase() ' Basic
  

    myDatabase.CloseDatabase() # Python
  

Commit

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

note

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.


Skladnja:

db.Commit()

Primer:

V Basicu

      ' 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()
    
V Pythonu

      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.

Skladnja:

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

Parametri:

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.

Primer:

The following examples in Basic and Python return a dataset with the records of a table named "Customers".

V Basicu

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

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

DAvg, DCount, DMin, DMax, DSum

Izračuna dano agregatno funkcijo na polju ali izrazu, ki pripada tabeli.

Po potrebi lahko določite stavek SQL WHERE kot filter, ki bo uporabljen pred agregatno funkcijo.

Skladnja:

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

Parametri:

expression: izraz SQL z imeni polj v oglatih oklepajih.

tablename: ime tabele (brez oglatih oklepajev).

criteria: stavek WHERE brez ključne besede "WHERE", v katerem so imena polj v oglatih oklepajih.

Primer:

Spodnji primer predvideva, da ima datoteka Employees.odb tabelo z imenom EmployeeData.

V Basicu

      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDB as Variant
      Set myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")
      ' Prešteje zaposlene v tabeli
      MsgBox myDB.DCount("[ID]", "EmployeeData")
      ' Vrne vsoto vseh plač v tabeli
      MsgBox myDB.DSum("[Salary]", "EmployeeData")
      ' Sledi nekaj primerov, kako lahko filtrirate tabele
      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%'")
    
V Pythonu

      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

Izračuna izraz SQL na posameznem zapisu, ki jih vrne stavek WHERE, določen s parametrom Criteria.

Če poizvedba vrne več zapisov, se uporabi le prvi. Uporabite parameter OrderClause, da ugotovite, kako so razvrščeni rezultati poizvedbe.

Skladnja:

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

Parametri:

expression: izraz SQL z imeni polj v oglatih oklepajih.

tablename: ime tabele (brez oglatih oklepajev).

criteria: stavek WHERE brez ključne besede "WHERE", v katerem so imena polj v oglatih oklepajih.

orderclause: stavek ORDER BY brez ključnih besed "ORDER BY". Imena polj morajo biti v oglatih oklepajih.

Primer:

V Basicu

      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'")
    
V Pythonu

      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

Shrani vsebino tabele ali rezultate poizvedbe SELECT ali izjave SQL v dvodimenzionalno polje. Prvi indeks tabele ustreza vrsticam, drugi indeks pa se nanaša na stolpce.

Določite lahko zgornjo mejo števila vrnjenih vrstic. Imena stolpcev lahko po želji vstavite v prvo vrstico polja.

Vrnjeno polje bo prazno, če ne vrne nobenih vrstic in glave stolpcev niso zahtevane.

Skladnja:

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

Parametri:

sqlcommand: ime tabele ali poizvedbe (brez oglatih oklepajev) ali SQL-izjava SELECT.

directsql: ko je True, pošlje ukaz SQL pogonu zbirke podatkov brez predhodne analize. Privzeta vrednost je False. Ta argument je pri tabelah prezrt. Za poizvedbe je uporabljena tista možnost, ki je veljala ob določitvi poizvedbe.

header: če je True, prva vrstica vrnjenega polja vsebuje glave stolpca.

maxrows: največje število vrnjenih vrstic. Privzeta vrednost je nič, kar pomeni, da število vrnjenih vrstic ni omejeno.

Primer:

Spodaj je nekaj primerov rabe metode GetRows:

V Basicu

      Dim queryResults as Variant
      ' Vrne vse vrstice v tabeli z glavami stolpcev
      queryResults = myDB.GetRows("EmployeeData", Header := True)
      ' Vrne prvih 50 zapisov zaposlenih, razvrščenih po polju 'FirstName'
      queryResults = myDB.GetRows("SELECT * FROM EmployeeData ORDER BY [FirstName]", MaxRows := 50)
    
V Pythonu

      queryResults = myDB.GetRows("EmployeeData", header = True)
      queryResults = myDB.GetRows("SELECT * FROM EmployeeData ORDER BY [FirstName]", maxrows = 50)
    

OpenFormDocument

Odpre navedeni dokument obrazca v navadnem načinu. Metoda vrne instanco razreda FormDocument, ki ustreza navedenemu dokumentu obrazca.

Če je dokument obrazca že odprt, bo okno obrazca dokumenta postalo aktivno.

Če navedeni dokument obrazca ne obstaja, vrne Nothing.

Skladnja:

svc.OpenFormDocument(formdocument: str): svc

Parametri:

formdocument: ime formDocument, ki ga želite odpreti, razlikuje med velikimi in malimi črkami.

Primer:

V Basicu

Večina dokumentov obrazcev je shranjenih v korenski mapi dokumenta programa Base in odprete jih lahko enostavno z njihovim imenom, kot v spodnjem primeru:


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

Če so dokumenti obrazca organizirani v mapah, je potrebno vključiti ime mape, da določite dokument obrazca, ki ga želite odpreti, kot je to nakazano v naslednjem primeru:


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

    formDoc = myDB.OpenFormDocument("myFormDocument")
  

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

OpenQuery

Odpre okno podatkovnega pogleda navedene poizvedbe in vrne instanco storitve Datasheet.

Če poizvedbe ni mogoče odpreti, vrne Nothing.

Skladnja:

db.OpenQuery(queryname: str): obj

Parametri:

queryname: ime obstoječe poizvedbe kot niz vrste String; razlikuje med velikimi in malimi črkami.

Primer:

V Basicu

      myDatabase.OpenQuery("MyQuery")
    
V Pythonu

      myDatabase.OpenQuery("MyQuery")
    

OpenSql

Izvede ukaz SQL SELECT, odpre okno podatkovnega pogleda z rezultati in vrne instanco storitve Datasheet.

Skladnja:

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

Parametri:

sql: niz, ki vsebuje veljavno izjavo SQL SELECT. Identifikatorji so lahko zaobjeti z oglatimi oklepaji.

directsql: ko je True, pošlje ukaz SQL pogonu zbirke podatkov brez predhodne analize (privzeta vrednost je False).

Primer:

V Basicu

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

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

OpenTable

Odpre okno podatkovnega pogleda navedene tabele in vrne instanco storitve Datasheet.

Skladnja:

db.OpenTable(tablename: str): obj

Parametri:

tablename: ime obstoječe tabele kot niz vrste String; razlikuje med velikimi in malimi črkami.

Primer:

V Basicu

      myDatabase.OpenTable("MyTable")
    
V Pythonu

      myDatabase.OpenTable("MyTable")
    

Rollback

Cancels all changes made to the database since the last Commit or Rollback call.

Skladnja:

db.Rollback()

Primer:

V Basicu

      myDB.SetTransactionMode(1)
      myDB.RunSql("UPDATE ...")
      ' ...
      If bSomeCondition Then
          myDB.Rollback()
      End If
    
V Pythonu

      myDB.SetTransactionMode(1)
      myDB.RunSql("UPDATE ...")
      # ...
      if bSomeCondition:
          myDB.Rollback()
    

RunSql

Izvede dejanje poizvedbe izjave SQL, kot je ustvarjanje tabele, pa tudi vstavljanje, posodabljanje in brisanje zapisov.

Metoda vrne True, če uspe.

tip

Metoda RunSql je zavrnjena s sporočilom o napaki, če je bila zbirka podatkov prej odprta v načinu samo za branje.


Skladnja:

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

Parametri:

sqlcommand: ime poizvedbe (brez oglatih oklepajev) ali ukaz SQL.

directsql: ko je True, pošlje ukaz SQL pogonu zbirke podatkov brez predhodne analize (privzeta vrednost je False). Za poizvedbe je uporabljena tista možnost, ki je veljala ob določitvi poizvedbe.

Primer:

V Basicu

      myDatabase.RunSql("INSERT INTO [EmployeeData] VALUES(25, 'Smith', 'John')", DirectSQL := True)
    
V Pythonu

      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.


Skladnja:

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

Parametri:

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.


Primer:

V Basicu

      myDB.SetTransactionMode(com.sun.star.sdbc.TransactionIsolation.REPEATABLE_READ)
      oDataset = myDB.CreateDataset("SELECT ...")
      ' ...
      ' Reset the transaction mode to default
      myDB.SetTransactionMode()
    
V Pythonu

      from com.sun.star.sdbc import TransactionIsolation
      myDB.SetTransactionMode(TransactionIsolation.REPEATABLE_READ)
      dataset = myDB.CreateDataset("SELECT ...")
      # ...
      myDB.SetTransactionMode()
    
warning

Vsi podprogrami ali identifikatorji ScriptForge Basic s predpono podčrtaja (»_«) so rezervirani za interno uporabo. Uporabi v makrih Basic ali skriptih Python niso namenjeni.