SFDatabases.Database zerbitzua

Database zerbitzuak Base dokumentuetan kapsulatutako edo deskribatutako datu-baseak atzitzea ahalbidetzen du. Zerbitzu honek honakoak egiteko metodoak ditu:

Datu-baseetako tauletako datuak atzitzeko.
SELECT kontsultak exekutatzeko eta funtzio agregatuak gauzatzeko.
SQL ekintza-instrukzioak exekutatzeko, adibidez INSERT, UPDATE, DELETE, etab.

Database zerbitzuaren instantzia bakoitzak datu-base bakar bat ordezkatzen du eta bere taula, kontsulta eta datuak erabiltzeko aukera irekitzen du.

Zerbitzu honek ez du ahalbidetzen datu-basea duen Base dokumentuko inprimakiak edo txostenak atzitzen. Horretarako, begiratu Base zerbitzuaren FormDocuments metodoa.

Zerbitzu horren eta datu-basearen arteko truke guztiak SQL bidez soilik gauzatzen dira.

SQL instrukzioak modu zuzenean edo zeharkakoan egin daitezke. Modu zuzenean, instrukzioa sintaxiaren egiaztatzerik edo berrikuspenik gabe transferituko zaio datu-basearen motorrari.

Emandako interfazeek taula sinpleak eta kontsulten zerrendak eskaintzen dituzte, bai eta datu-baseko datuak atzitzeko modua ere.

SQL instrukzioak irakurgarriagoak izan daitezen, erabili kortxeteak "[ ]" taulen, kontsulten eta eremuen izenak inguratzeko, beste inguratze-karaktere batzuk RDBMS jakin batzuetan esklusiboak izan baitaitezke. Hala ere, kontuan hartu inguratze-karaktereak derrigorrezkoak direla testuinguru honetan.

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.

Zerbitzuari deitzea

Database zerbitzua erabiltzeko, derrigorrezkoa da ScriptForge liburutegia kargatzea edo inportatzea:

• Basic makroak erabiltzkeo, ScriptForge liburutegia kargatu behar da honako instrukzioa erabiliz:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python scriptak erabiltzeko, berriz, scriptforge modulu baten inportazioa behar dute:
from scriptforge import CreateScriptService

Sintaxia:

Database zerbitzuaren instantzia bat sortzeko, erabili CreateScriptService metodoa:

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

Goian deskribatutako sintaxian, "SFDatabases.Database" zein "Database" erabili daitezke CreateScriptService metodoaren lehen argumentu gisa.

Parametroak:

filename: Base fitxategiaren izena. SF_FileSystem.FileNaming notazioa erabilita adierazi behar da.

registrationname: Erregistratutako datu-base baten izena. filename ematen bada, argumentu hori ez da erabili behar.

Era berean, registrationname zehaten bada, filename parametroa ez da definitu behar.

readonly: Datu-basea irakurtzeko moduan soilik irekiko den zehazten du (Balio lehenetsia = True (egia)).

user, password: Datu-basearen zerbitzariarekin konektatzeko parametro gehigarriak.

Adibidea:

Basic lengoaian


      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDatabase as Object
      Set myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      ' Exekutatu kontsultak, SQL instrukzioak...
      myDatabase.CloseDatabase()

Python lengoaian


      from scriptforge import CreateScriptService
      myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      # Exekutatu kontsultak, SQL instrukzioak...
      myDatabase.CloseDatabase()

Datu-baseak atzitzea UI zerbitzua erabilita

Posible da Base dokumentu bati lotutako datu-basea ScriptForge.UI zerbitzuaren bidez atzitzea, beheko adibideetan ikusten den moduan:

Basic lengoaian


      Dim myDoc As Object, myDatabase As Object, ui As Object
      Set ui = CreateScriptService("UI")
      Set myDoc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      ' Erabiltzailea eta pasahitza behean ematen dira, beharrezkoak badira
      Set myDatabase = myDoc.GetDatabase()
      ' Exekutatu kontsultak, SQL instrukzioak...
      myDatabase.CloseDatabase()
      myDoc.CloseDocument()

Python lengoaian


      ui = CreateScriptService("UI")
      doc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      # Erabiltzailea eta pasahitza behean ematen dira, beharrezkoak badira
      myDatabase = doc.GetDatabase()
      # Exekutatu kontsultak, SQL instrukzioak...
      myDatabase.CloseDatabase()
      doc.CloseDocument()

Goian erabilitako GetDatabase metodoa ScriptForgen Base zerbitzuarena da.

Propietateak

Izena	Irakurtzeko soilik	Mota	Deskribapena
Queries	Bai	Kateen matrizea	Biltegiratutako kontsulten zerrenda
Tables	Bai	Kateen matrizea	Biltegiratutako taulen zerrenda.
XConnection	Bai	XConnection	Datu-basearen uneko konexioa ordezkatzen duen UNO objektua.
XMetaData	Bai	XDatabaseMetaData	Datu-basearen sistema-atributuak deskribatzen dituzten metadatuak ordezkatzen dituen UNO objektua.

Database zerbitzuko metodoen zerrenda
CloseDatabase Commit CreateDataset DAvg DCount DMin	DMax DSum DLookup GetRows OpenFormDocument OpenQuery	OpenSql OpenTable Rollback RunSql SetTransactionMode

CloseDatabase

Datu-basearen uneko konexioa ixten du.

Sintaxia:

db.CloseDatabase()

Adibidea:


    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.

Sintaxia:

db.Commit()

Adibidea:

Basic lengoaian


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

Python lengoaian


      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.

Sintaxia:

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

Parametroak:

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.

Adibidea:

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

Basic lengoaian


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

Python lengoaian


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

DAvg, DCount, DMin, DMax, DSum

Emandako agregazio-funtzioa kalkulatzen du taula batekoa den eremu edo adierazpen batean.

Aukeran, SQLren WHERE klausula zehaztu daiteke agregazio-funtzioaren aurretik aplikatuko den iragazki gisa.

Sintaxia:

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

Parametroak:

expression: SQL adierazpen bat, non eremu-izenak kortxeteekin inguratuta dauden.

tablename: Taula baten izena (kortxeterik gabe).

criteria: WHERE klausula bat "WHERE" gako-hitzik gabe, non eremu-izenak kortxeteekin inguratuta dauden.

Adibidea:

Beheko adibidean, Employees.odb fitxategiak EmployeeData izeneko taula bat duela ulertzen da.

Basic lengoaian


      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDB as Variant
      Set myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")
      ' Taulako enplegatu kopurua zenbatzen du
      MsgBox myDB.DCount("[ID]", "EmployeeData")
      ' Taulako soldata guztien batuketa itzultzen du
      MsgBox myDB.DSum("[Salary]", "EmployeeData")
      ' Behean, taulak nola iragazten diren erakusten dituzten zenbait adibide daude
      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%'")

Python lengoaian


      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

SQL adierapzen bat kalkulatzen du Criteria parametroak definitutako WHERE klausulak itzulitako erregistro batak batean.

Kontsultak erregistro anitz itzultzen baditu, lehena soilik hartuko da kontuan. Erabili OrderClause parametroa kontsulta-emaitzak nola ordenatuko diren zehazteko.

Sintaxia:

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

Parametroak:

expression: SQL adierazpen bat, non eremu-izenak kortxeteekin inguratuta dauden.

tablename: Taula baten izena (kortxeterik gabe).

criteria: WHERE klausula bat "WHERE" gako-hitzik gabe, non eremu-izenak kortxeteekin inguratuta dauden.

orderclause: ORDER BY klausula bat "ORDER BY" gako-hitzik gabe. Eremu-izenek ez dute kortxeteekin inguratuta egon behar.

Adibidea:

Basic lengoaian


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

Python lengoaian


      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

Taula baten edukiak edo SELECT kontsulta baten edo SQL instrukzio baten emaitzak bi dimentsiotako matrize batean biltegiratzen ditu. Matrizeko lehen indizea erregistroei dagokie eta bigarren indizea zutabei dagokie.

Goiko muga bat zehaztu daiteke itzulitako errenkaden kopurua mugatzeko. Aukeran, zutabe-izenak txertatu daitezke matrizearen lehen errenkadan.

Itzulitako matrizea hutsik egongo da errenkadarik ez bada itzuli eta zutabe-goiburukoak beharrezkoak ez badira.

Sintaxia:

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

Parametroak:

sqlcommand: Taula baten edo kontsulta baten izena (kortxeterik gabe) edo SELECT SQL instrukzio bat.

directsql: True (egia) denean, SQL komandoa aurretiko analisirik gabe bidaltzen zaio datu-basearen motorrari. Balio lehenetsia False (faltsua) da. Taulen kasuan, ez ikusiarena egiten zaio argumentuari. Kontsultetan, kontsulta definitu zenean ezarritako aukerak aplikatuko dira.

header: True (egia) denean, itzulitako matrizearen lehen errenkadak zutabe-goiburukoak ditu.

maxrows: Itzuliko den gehieneko errenkada kopurua. Balio lehenetsia zero da, horrek esan nahi du ez dagoela mugarik itzulitako errenkada kopuruan.

Adibidea:

Behean, GetRows metodoa nola erabili daitekeen azaltzen duten zenbait adibide:

Basic lengoaian


      Dim queryResults as Variant
      ' Taulako errenkada guztiak itzultzen ditu, zutabe-goiburukoekin
      queryResults = myDB.GetRows("EmployeeData", Header := True)
      ' Lehen 50 enplegatuen erregistroak itzultzen ditu, 'FirstName' eremuaren arabera ordenatuta
      queryResults = myDB.GetRows("SELECT * FROM EmployeeData ORDER BY [FirstName]", MaxRows := 50)

Python lengoaian


      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.

Sintaxia:

svc.OpenFormDocument(formdocument: str): svc

Parametroak:

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

Adibidea:

Basic lengoaian

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

Python lengoaian


    formDoc = myDB.OpenFormDocument("myFormDocument")


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

OpenQuery

Zehaztutako kontsultaren 'Datu-ikuspegia' leihoa irekitzen du eta Datasheet zerbitzuaren instantzia bat itzultzen du.

Ezin bada kontsulta ireki, Nothing itzuliko da.

Sintaxia:

db.OpenQuery(queryname: str): obj

Parametroak:

queryname: Jadanik badagoen kontsulta baten izena, maiuskulak/minuskulak bereizten dituen kate gisa.

Adibidea:

Basic lengoaian


      myDatabase.OpenQuery("MyQuery")

Python lengoaian


      myDatabase.OpenQuery("MyQuery")

OpenSql

SQL SELECT komando bat exekutatzen du, 'Datu-ikuspegia' leiho bat irekitzen du emaitzekin eta Datasheet zerbitzuaren instantzia bat itzultzen du.

Sintaxia:

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

Parametroak:

sql: Baliozko SQL SELECT instrukzio bat duen katea. Identifikatzaileak kortxetez inguratuta egon daitezke.

directsql: True bada, SQL komandoa aurretiko analisirik gabe bidaliko da datu-basearen motorrera (Balio lehenetsia = False).

Adibidea:

Basic lengoaian


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

Python lengoaian


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

OpenTable

Zehaztutako taularen 'Datu-ikuspegia' leihoa irekitzen du eta Datasheet zerbitzuaren instantzia bat itzultzen du.

Sintaxia:

db.OpenTable(tablename: str): obj

Parametroak:

tablename: Jadanik badagoen taula baten izena, maiuskulak/minuskulak bereizten dituen kate gisa.

Adibidea:

Basic lengoaian


      myDatabase.OpenTable("MyTable")

Python lengoaian


      myDatabase.OpenTable("MyTable")

Rollback

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

Sintaxia:

db.Rollback()

Adibidea:

Basic lengoaian


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

Python lengoaian


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

RunSql

SQL instrukzio baten ekintza-kontsulta bat exekutatzen du, adibidez taula bat sortzea edo erregistroak txertatzea, eguneratzea edo ezabatzea.

Metodoak True itzultzen du arrakasta duenean.

RunSql metodoa errore-mezu batekin baztertzen da datu-basea lehenago soilik irakurtzeko moduan ireki bada.

Sintaxia:

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

Parametroak:

sqlcommand: Kontsulta-izen bat (kortxeterik gabe) edo SQL instrukzio bat.

directsql: True bada, SQL komandoa aurretiko analisirik gabe bidaliko da datu-basearen motorrera. (Lehenetsia = False). Kontsultetan, kontsulta definitu zenean ezarritako aukera aplikatuko da.

Adibidea:

Basic lengoaian


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

Python lengoaian


      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.

Sintaxia:

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

Parametroak:

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.

Adibidea:

Basic lengoaian


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

Python lengoaian


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

Azpimarraren karaktere bat, "_", aurrizki gisa duten ScriptForge Basic errutina edo identifikatzaile guztiak barneko erabilerarako erreserbatuta daude. Ez dira Basic makroetan edo Python scriptetan erabili behar.

SFDatabases.Datasheet service

SFDatabases.Dataset service

SFDocuments.Document zerbitzua

SFDocuments.Form zerbitzua

ScriptForge.UI zerbitzua