Услуга SFDatabases.Database

Услугата Database предоставя достъп до вградени или описани в документи на Base бази от данни. Тази услуга предлага методи за:

получаване на достъп до таблици в база от данни
стартиране на заявки SELECT и изчисляване на агрегатни функции
изпълнение на оператори за действия на SQL като INSERT, UPDATE, DELETE и т.н.

Всеки екземпляр на услугата Database представя единична база от данни и дава достъп до нейните таблици, заявки и данни.

Тази услуга не предлага достъп до формуляри или справки в документа на Base, който съдържа базата от данни. За достъп до формуляри в документи на Base вижте метода FormDocuments на услугата Base.

Целият обмен между тази услуга и базата от данни се извършва само посредством SQL.

Оператори на SQL може да се изпълняват в пряк или непряк режим. В пряк режим операторът се предава към СУБД без проверка на синтаксиса или преглеждане.

Предлаганите интерфейси включват прости списъци на таблиците и заявките, както и достъп до данните в базата от данни.

За да направите операторите на SQL по-четливи, може да ограждате имената на таблици, заявки и полета с квадратни скоби „[ ]“, вместо с други ограждащи знаци, които може да се поддържат само от определени системи за управление на бази от данни (СУБД). Но имайте предвид, че в този контекст ограждащите знаци са задължителни.

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.

Извикване на услугата

Преди да използвате услугата Database, библиотеката ScriptForge трябва да бъде заредена или импортирана:

• Макросите на Basic изискват зареждане на библиотеката ScriptForge чрез следния оператор:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Скриптовете на Python изискват импортиране от модула scriptforge:
from scriptforge import CreateScriptService

Синтаксис:

За да създадете екземпляр на услугата Database, може да използвате метода CreateScriptService:

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

В описания по-горе синтаксис можете да използвате или "SFDatabases.Database", или просто "Database" като първи аргумент на метода CreateScriptService.

Параметри:

filename: името на файла на Base. То трябва да следва нотацията, зададена с SF_FileSystem.FileNaming.

registrationname: името на регистрирана база от данни. Ако е подаден filename, този аргумент не трябва да се използва.

Обратно, ако е зададен registrationname, параметърът filename не трябва да е дефиниран.

readonly: определя дали базата от данни да се отвори само за четене (подразбира се True).

user, password: допълнителни параметри на връзката към сървъра на базата от данни.

Пример:

В Basic


      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDatabase as Object
      Set myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      ' Изпълняване на заявки, оператори на SQL, ...
      myDatabase.CloseDatabase()

В Python


      from scriptforge import CreateScriptService
      myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      # Изпълняване на заявки, оператори на SQL, ...
      myDatabase.CloseDatabase()

Достъп до бази от данни с услугата UI

Достъпът до базата от данни, свързана с документ на Base, е възможен и чрез услугата ScriptForge.UI, както е показано в следващите примери:

В Basic


      Dim myDoc As Object, myDatabase As Object, ui As Object
      Set ui = CreateScriptService("UI")
      Set myDoc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      ' Потребителят (user) и паролата (password) се подават по-долу, ако е необходимо.
      Set myDatabase = myDoc.GetDatabase()
      ' Изпълняване на заявки, оператори на SQL, ...
      myDatabase.CloseDatabase()
      myDoc.CloseDocument()

В Python


      ui = CreateScriptService("UI")
      doc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      # Потребителят (user) и паролата (password) се подават по-долу, ако е необходимо.
      myDatabase = doc.GetDatabase()
      # Изпълняване на заявки, оператори на SQL, ...
      myDatabase.CloseDatabase()
      doc.CloseDocument()

Методът GetDatabase, използван в горния пример, е част от услугата Base на ScriptForge.

Свойства

Име	Само за четене	Тип	Описание
Queries	Да	Масив от низове	Списъкът от съхранени заявки.
Tables	Да	Масив от низове	Списъкът от съхранени таблици.
XConnection	Да	XConnection	UNO обектът, представящ текущата връзка с база от данни.
XMetaData	Да	XDatabaseMetaData	UNO обектът, представящ метаданните, които описват системните атрибути на базата от данни.

Списък с методи на услугата Database
CloseDatabase Commit CreateDataset DAvg DCount DMin	DMax DSum DLookup GetRows OpenFormDocument OpenQuery	OpenSql OpenTable Rollback RunSql SetTransactionMode

CloseDatabase

Затваря текущата връзка с база от данни.

Синтаксис:

db.CloseDatabase()

Пример:


    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.

Синтаксис:

db.Commit()

Пример:

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

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

Синтаксис:

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

Параметри:

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.

Пример:

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

В Basic


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

В Python


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

DAvg, DCount, DMin, DMax, DSum

Изчислява дадената агрегатна функция върху поле или израз от таблица.

По желание може да се зададе клауза на SQL WHERE като филтър, който да бъде приложен преди агрегатната функция.

Синтаксис:

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

Параметри:

expression: израз на SQL, в който имената на полета са оградени с квадратни скоби.

tablename: име на таблица (без квадратни скоби).

criteria: клауза WHERE без ключовата дума WHERE, в която имената на полета са оградени с квадратни скоби.

Пример:

В долния пример се приема, че файлът Employees.odb съдържа таблица с име EmployeeData.

В Basic


      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDB as Variant
      Set myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")
      ' Преброява служителите в таблицата.
      MsgBox myDB.DCount("[ID]", "EmployeeData")
      ' Връща сумата на всички заплати в таблицата.
      MsgBox myDB.DSum("[Salary]", "EmployeeData")
      ' Следват няколко примера за филтриране на таблици.
      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


      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 върху единичен запис, върнат от клауза WHERE, която е дефинирана в параметъра Criteria.

Ако заявката върне няколко записа, се взема само първият от тях. Използвайте параметъра OrderClause, за да определите как се сортират резултатите от заявката.

Синтаксис:

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

Параметри:

expression: израз на SQL, в който имената на полета са оградени с квадратни скоби.

tablename: име на таблица (без квадратни скоби).

criteria: клауза WHERE без ключовата дума WHERE, в която имената на полета са оградени с квадратни скоби.

orderclause: клауза ORDER BY без ключовите думи ORDER BY. Имената на полета трябва да бъдат оградени с квадратни скоби.

Пример:

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

В 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

Съхранява съдържанието на таблица или резултатите от заявка SELECT или оператор на SQL в двуизмерен масив. Първият индекс на масива съответства на редовете, а вторият представя колоните.

Може да бъде зададена горна граница за броя върнати записи. По желание имената на колоните могат да бъдат вмъкнати в първия ред на масива.

Резултатният масив ще бъде празен, ако не са върнати редове и не се изискват заглавия на колони.

Синтаксис:

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

Параметри:

sqlcommand: име на таблица или заявка (без квадратни скоби) или оператор SELECT на SQL.

directsql: когато е True, командата на SQL се изпраща към СУБД без предварителен анализ. Подразбира се False. Аргументът се игнорира за таблици. За заявки прилаганата настройка е тази, която е била зададена при създаване на заявката.

header: когато е True, първият ред на върнатия масив съдържа заглавията на колоните.

maxrows: максималният брой върнати редове. Подразбира се нула, което означава, че няма ограничение за броя връщани редове.

Пример:

Следват няколко примера за употребата на метода GetRows:

В Basic


      Dim queryResults as Variant
      ' Връща всички редове в таблицата и заглавията на колоните.
      queryResults = myDB.GetRows("EmployeeData", Header := True)
      ' Връща първите 50 записа за служители, подредени по полето FirstName.
      queryResults = myDB.GetRows("SELECT * FROM EmployeeData ORDER BY [FirstName]", MaxRows := 50)

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

Синтаксис:

svc.OpenFormDocument(formdocument: str): svc

Параметри:

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

Пример:

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

В Python


    formDoc = myDB.OpenFormDocument("myFormDocument")


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

OpenQuery

Отваря прозореца „Изглед с данни“ на указаната заявка и връща екземпляр на услугата Datasheet.

Ако заявката не може да бъде отворена, се връща Nothing.

Синтаксис:

db.OpenQuery(queryname: str): obj

Параметри:

queryname: името на съществуваща заявка като низ, малките и главните букви се различават.

Пример:

В Basic


      myDatabase.OpenQuery("MyQuery")

В Python


      myDatabase.OpenQuery("MyQuery")

OpenSql

Изпълнява команда SELECT на SQL, отваря прозорец „Изглед с данни“ с резултатите и връща екземпляр на услугата Datasheet.

Синтаксис:

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

Параметри:

sql: низ, съдържащ валиден оператор SELECT на SQL. Идентификаторите може да бъдат оградени с квадратни скоби.

directsql: когато е True, командата на SQL се изпраща към системата за управление на бази от данни без предварителен анализ (подразбира се False).

Пример:

В Basic


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

В Python


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

OpenTable

Отваря прозореца „Изглед с данни“ на указаната таблица и връща екземпляр на услугата Datasheet.

Синтаксис:

db.OpenTable(tablename: str): obj

Параметри:

tablename: името на съществуваща таблица като низ, малките и главните букви се различават.

Пример:

В Basic


      myDatabase.OpenTable("MyTable")

В Python


      myDatabase.OpenTable("MyTable")

Rollback

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

Синтаксис:

db.Rollback()

Пример:

В Basic


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

В Python


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

RunSql

Executes an action query of an SQL statement such as creating a table, as well as inserting, updating and deleting records.

Методът връща True при успех.

Методът RunSql се отказва със съобщение за грешка, ако базата от данни е била отворена в режим само за четене.

Синтаксис:

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

Параметри:

sqlcommand: име на заявка (без квадратни скоби) или оператор на SQL.

directsql: когато е True, командата на SQL се изпраща към СУБД без предварителен анализ. Подразбира се False. За заявки прилаганата настройка е тази, която е била зададена при създаване на заявката.

Пример:

В Basic


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

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

Синтаксис:

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

Параметри:

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.

Пример:

В Basic


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

В Python


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

В ScriptForge всички подпрограми или идентификатори на Basic с префикс „_“ са запазени за вътрешна употреба. Те не са предназначени за използване в макроси на Basic.

SFDatabases.Datasheet service

SFDatabases.Dataset service

SFDocuments.Document service

SFDocuments.Form service

ScriptForge.UI service