Vsebina

# Storitev SFDatabases.Database

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

- pridobivanje dostopa do podatkov v tabelah zbirke podatkov;

- zagon povpraševanj SELECT in izvajanje sestavljenih funkcij;

- izvajanje ukazov dejanj SQL , kot so INSERT, UPDATE, DELETE itn.

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.

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.

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.

## Ravnanje s transakcijami

Zbirka podatkov privzeto upravlja s transakcijami v načinu samodejne potrditve, kar pomeni, da se potrditev opravi po vsakem ukazu SQL.

Uporabite metodo SetTransactionMode, da spremenite privzeto vedenje, kar omogoča ročne uveljavitve in povrnitve.

Metodi Commit in Rollback se uporabljata za razločevanje transakcij.

V LibreOffice je pet vrst načinov izolacije transakcij, kot je definirano v skupini konstant com.sun.star.sdbc.TransactionIsolation:

Konstanta | Vrednost | Interpretacija
--- | --- | ---
NONE | 0 | Ravnanje s transakcijami je onemogočeno in zbirka podatkov je nastavljena na privzeti način samodejnega potrjevanja.
READ_UNCOMMITTED | 1 | Dogodijo se lahko branja nepotrjenih podatkov, neponovljiva branja in fantomska branja. Če transakcija spremeni vrstico, lahko druga transakcija prebere te spremembe, čeprav niso bile potrjene.
READ_COMMITTED | 2 | Branja nepotrjenih podatkov so preprečena, medtem ko se neponovljiva in fantomska branja lahko dogodijo. Ta raven preprečuje, da bi bile vrstice z nepotrjenimi spremembami prebrane.
REPEATABLE_READ | 4 | Branja nepotrjenih podatkov in neponovljiva branja so preprečena. Fantomska branja se lahko zgodijo. Poleg preprečevanja branja nepotrjenih podatkov preprečuje tudi, da dve bralni operaciji v isti transakciji vrneta različne rezultate.
SERIALIZABLE | 8 | Branja nepotrjenih podatkov ter neponovljiva in fantomska branja so preprečena. Poleg omejitev prejšnje ravni zagotavlja tudi, da ostane nabor zapisov, ki se ujemajo s pogojem WHERE, nespremenjen v okviru iste transakcije.

Preberite sestavek na Wikipediji o Izolaciji v sistemih zbirk podatkov (v angl.), da izveste več o integriteti transakcij.

## Priklic storitve

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

• 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

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

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

Potrdi vse opravljene posodobitve od prejšnjega klica Commit ali Rollback.

Ta metoda je prezrta, če so potrditve izvedene samodejno po vsakem ukazu SQL, t.j. zbirka podatkov je nastavljena na privzeti način samodejnega potrjevanja.

### Skladnja:

db.Commit()

### Primer:

##### V Basicu

          ' Določi raven transakcije REPEATABLE_READ
          myDB.SetTransactionMode(4)
          myDB.RunSql("UPDATE ...")
          myDB.Commit()
          myDB.RunSql("DELETE ...")
          ' Preizkusi nekatere pogoje pred potrditvijo
          If bSomeCondition Then
              myDB.Commit()
          Else
              myDB.Rollback()
          End If
          ' Obnovi način samodejnega potrjevanja
          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

Ustvari instanco storitve Dataset na osnovi tabele, poizvedbe ali izjave SQL SELECT.

### Skladnja:

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

### Parametri:

sqlcommand: ime tabele, ime poizvedbe ali veljavna izjava SQL SELECT. Identifikatorji so lahko zaobjeti z oglatimi oklepaji. Ta argument razlikuje med velikimi in malimi črkami.

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

filter: določa pogoj, katerega morajo izpolnjevati zapisi, da so vključeni v vrnjeni nabor podatkov. Ta argument je izražen kot stavek SQL WHERE brez ključne besede »WHERE«.

orderby: določa, v kakšnem zaporedju naj bodo prikazani zapisi kot stavek SQL ORDER BY, vendar brez ključne besede »ORDER BY«.

### Primer:

Spodnja primera v Basicu in Pythonu vrneta nabor podatkov z zapisi tabele, imenovane »Stranke«.

##### V Basicu

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

##### V Pythonu

          dataset = myDatabase.CreateDataset("Stranke", Filter = "[Ime] 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

Prekliče vse spremembe, opravljene v zbirki podatkov od zadnjega klica Commit ali Rollback.

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

Ta metoda vrne True, če uspe.

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

Določa raven izolacije v transakcijah zbirke podatkov.

Zbirke podatkov privzeto opravljajo transakcije v načinu samodejnega potrjevanja, kar pomeni, da je Commit samodejno izveden po vsaki izjavi SQL.

Uporabite to metodo, da ročno določite raven izolacije transakcij. Če je nastavljen drug način transakcij od NONE, mora skript eksplicitno klicati metodo Commit, da uveljavi spremembe v zbirki podatkov.

Ta metoda vrne True, če uspe.

Sprememba načina transakcij zapre vse instance Dataset, ustvarjene iz trenutne zbirke podatkov.

### Skladnja:

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

### Parametri:

transactionmode: določa način transakcije. Ta argument mora biti ena od konstant, definiranih v com.sun.star.sdbc.TransactionIsolation (privzeta vrednost je NONE).

Oglejte si stran pomoči Ravnanje s transakcijami (v angl.), da izveste več o ravneh izolacije transakcij v LibreOffice.

### Primer:

##### V Basicu

          myDB.SetTransactionMode(com.sun.star.sdbc.TransactionIsolation.REPEATABLE_READ)
          oDataset = myDB.CreateDataset("SELECT ...")
          ' ...
          ' Ponastavi način transakcije na privzetega
          myDB.SetTransactionMode()

##### V Pythonu

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

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

Podobne teme

Storitev SFDatabases.Datasheet

Storitev SFDatabases.Dataset

Storitev SFDocuments.Document

Storitev SFDocuments.Form

Storitev ScriptForge.UI