Serviço SFDatabases.Database

O serviço Database permite o acesso a bancos de dados embutidos ou descritos por documentos Base. Este serviço fornece métodos para:

Cada instância do serviço Database representa um único banco de dados e dá acesso a suas tabelas, consultas e dados.

Este serviço não fornece acesso aos formulários ou relatórios do documento Base que contém o banco de dados. Para acessar os formulários em um documento Base, consulte o método FormDocuments do serviço Base.

note

Todas as trocas entre este serviço e o banco de dados são feitas usando SQL apenas.


Comandos SQL podem ser executados nos modos direto ou indireto. No modo direto o comando é transferido ao banco de dados sem verificação ou revisão de sintaxe.

Os interfaces fornecidas incluem tabelas e listas de consultas, bem como acesso aos dados contidos no banco de dados.

tip

Para tornar instruções SQL mais legíveis, colchetes "[ ]" podem ser usados em volta de nomes de tabelas, consultas e campos em vez de usar outros caracteres que pode ser exclusivos de certos Sistemas de Gerenciamento de Bancos de Dados Relacionais (SGBDR). Porém esteja ciente que caracteres delimitadores são obrigatórios neste contexto.


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.


Invocação do serviço

Antes de usar o serviço Database a biblioteca ScriptForge precisa ser carregada ou importada:

note

• Macros BASIC precisam carregar a biblioteca ScriptForge usando a seguinte instrução:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Scripts Python exigem uma importação do módulo scriptforge:
from scriptforge import CreateScriptService


Sintaxe:

Para criar uma instância do serviço Database você pode usar o método CreateScriptService:

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

note

Na sintaxe descrita acima pode-se usar "SFDatabases.Database" ou simplesmente "Database" como o primeiro argumento do método CreateScriptService.


Parâmetros:

filename: Nome do arquivo Base. Deve ser expresso usando a notação SF_FileSystem.FileNaming.

registrationname: Nome de banco de dados registrado. Se filename for especificado, este argumento não deve ser usado.

Por outro lado, se o argumento registrationname for especificado o parâmetro filename não deve ser definido.

readonly: Determina se o banco de dados será aberto como somente leitura (Padrão = True).

user, password: Parâmetros adicionais de conexão a serem enviados ao servidor de banco de dados.

Exemplo:

Em Basic

      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDatabase as Object
      Set myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      ' Executa consultas, comandos SQL, etc...
      myDatabase.CloseDatabase()
    
Em Python

      from scriptforge import CreateScriptService
      myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      # Executa consultas, comandos SQL, etc...
      myDatabase.CloseDatabase()
    

Acessando Bancos de Dados com o Serviço UI

Também é possível acessar o banco de dados associado a um documento Base usando o serviço ScriptForge.UI, conforme mostrado no exemplo abaixo:

Em Basic

      Dim myDoc As Object, myDatabase As Object, ui As Object
      Set ui = CreateScriptService("UI")
      Set myDoc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      ' Nome de usuário e senha são informados abaixo, se necessário
      Set myDatabase = myDoc.GetDatabase()
      ' Executa consultas, comandos SQL, etc...
      myDatabase.CloseDatabase()
      myDoc.CloseDocument()
    
Em Python

      ui = CreateScriptService("UI")
      doc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      # Nome de usuário e senha são informados abaixo, se necessário
      myDatabase = doc.GetDatabase()
      # Executa consultas, comandos SQL, etc...
      myDatabase.CloseDatabase()
      doc.CloseDocument()
    
tip

O método GetDatabase usado no exemplo acima é parte do serviço Base da biblioteca ScriptForge.


Propriedades

Nome

Somente leitura

Tipo

Descrição

Queries

Sim

Array de Strings

Lista das consultas armazenadas.

Tables

Sim

Array de Strings

Lista de tabelas armazenadas.

XConnection

Sim

XConnection

Objeto UNO representando a atual conexão de banco de dados.

XMetaData

Sim

XDatabaseMetaData

Objeto UNO representando os metadados que descrevem os atributos do sistema de banco de dados.


Lista de Métodos no Serviço Database

CloseDatabase
Commit
CreateDataset
DAvg
DCount
DMin

DMax
DSum
DLookup
GetRows
OpenFormDocument
OpenQuery

OpenSql
OpenTable
Rollback
RunSql
SetTransactionMode


CloseDatabase

Fecha a conexão atual com a base de dados.

Sintaxe:

db.CloseDatabase()

Exemplo:


    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.


Sintaxe:

db.Commit()

Exemplo:

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

Sintaxe:

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

Parâmetros:

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.

Exemplo:

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

Em Basic

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

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

DAvg, DCount, DMin, DMax, DSum

Computa a função agregada em um campo ou expressão pertencente a uma tabela.

Opcionalmente, uma cláusula WHERE pode ser especificada como um filtro que será aplicado antes da função agregada.

Sintaxe:

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

Parâmetros:

expression: Uma expressão SQL na qual os nomes dos campos são delimitados por colchetes.

tablename: Nome da tabela (sem colchetes).

criteria: Uma cláusula WHERE sem a palavra-chave "WHERE", na qual os nomes dos campos são delimitados por colchetes.

Exemplo:

O exemplo abaixo assume que o arquivo Employees.odb possui uma tabela com o nome EmployeeData.

Em Basic

      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDB as Variant
      Set myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")
      ' Conta o número de empregados na tabela
      MsgBox myDB.DCount("[ID]", "EmployeeData")
      ' Retorna a soma de todos os salários na tabela
      MsgBox myDB.DSum("[Salary]", "EmployeeData")
      ' Abaixo estão alguns exemplos de como tabelas podem ser filtradas
      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%'")
    
Em 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

Calcula uma expressão SQL em um único registro retornado por uma cláusula WHERE definida pelo parâmetro Criteria.

Se a consulta retornar múltiplos registros, apenas o primeiro é considerado. Use o parâmetro OrderClause para determinar como os resultados da consulta serão ordenados.

Sintaxe:

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

Parâmetros:

expression: Uma expressão SQL na qual os nomes dos campos são delimitados por colchetes.

tablename: Nome da tabela (sem colchetes).

criteria: Uma cláusula WHERE sem a palavra-chave "WHERE", na qual os nomes dos campos são delimitados por colchetes.

orderclause: Uma cláusula ORDER BY sem a palavra-chave "ORDER BY". Nomes de campos devem ser delimitados por colchetes.

Exemplo:

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

Armazena o conteúdo de uma tabela ou os resultados de uma consulta SELECT ou de um comando SQL em um Array de duas dimensões. O primeiro índice do Array corresponde às linhas e o segundo índice refere-se às colunas.

Um limite superior pode ser especificado para a quantidade de linhas retornadas. Opcionalmente os nomes das colunas podem ser inseridos na primeira linha do Array.

O Array retornado pode estar vazio se nenhuma linha for retornada e os cabeçalhos das colunas não tiverem sido requeridos.

Sintaxe:

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

Parâmetros:

sqlcommand: Um nome de tabela ou consulta (sem colchetes) ou um comando SQL do tipo SELECT.

directsql: Se True, o comando SQL é enviado ao banco de dados diretamente sem análise prévia. O valor padrão é False. Este argumento é ignorado para tabelas. Para consultas, a opção aplicada é a definida quando a consulta foi criada.

header: Se True, a primeira linha do array retornado contém os cabeçalhos das colunas.

maxrows: Quantidade máxima de linhas a serem retornadas. O valor padrão é zero, indicando que não há limite para o número de registros retornados.

Exemplo:

Abaixo estão alguns exemplos de como o método GetRows pode ser usado:

Em Basic

      Dim queryResults as Variant
      ' Retorna todas as linhas na tabela juntamente com os cabeçalhos
      queryResults = myDB.GetRows("EmployeeData", Header := True)
      ' Retorna os primeiros 50 registros de funcionários ordenados pelo campo 'FirstName'
      queryResults = myDB.GetRows("SELECT * FROM EmployeeData ORDER BY [FirstName]", MaxRows := 50)
    
Em 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.

Sintaxe:

svc.OpenFormDocument(formdocument: str): svc

Parâmetros:

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

Exemplo:

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

    formDoc = myDB.OpenFormDocument("myFormDocument")
  

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

OpenQuery

Abre a janela de exibição de dados da consulta especificada e retorna uma instância de serviço da Datasheet.

Se a consulta não puder ser aberta, retorna Nothing.

Sintaxe:

db.OpenQuery(queryname: str): obj

Parâmetros:

queryname: o nome de uma consulta existente como uma string que diferencia maiúsculas de minúsculas.

Exemplo:

Em Basic

      myDatabase.OpenQuery("MyQuery")
    
Em Python

      myDatabase.OpenQuery("MyQuery")
    

OpenSql

Executa um comando SQL SELECT, abre uma janela de exibição de dados com os resultados e retorna uma instância do serviço Datasheet.

Sintaxe:

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

Parâmetros:

sql: Uma string contendo uma instrução SQL SELECT válida. Os identificadores podem ser colocados entre colchetes.

directsql: Quando True, o comando SQL é enviado para o mecanismo de banco de dados sem pré-análise (Padrão = False).

Exemplo:

Em Basic

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

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

OpenTable

Abre a janela Exibição de dados da tabela especificada e retorna uma instância do serviço Datasheet.

Sintaxe:

db.OpenTable(tablename: str): obj

Parâmetros:

tablename: O nome de uma tabela existente como uma String que diferencia maiúsculas de minúsculas.

Exemplo:

Em Basic

      myDatabase.OpenTable("MyTable")
    
Em Python

      myDatabase.OpenTable("MyTable")
    

Rollback

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

Sintaxe:

db.Rollback()

Exemplo:

Em Basic

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

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

RunSql

Executa comandos SQL de ação, tais como como a criação tabelas, bem como a inserção, atualização ou remoção de registros.

Este método retorna True quando for bem-sucedido.

tip

O método RunSql é rejeitado com uma mensagem de erro se o banco de dados foi previamente aberto no modo somente leitura.


Sintaxe:

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

Parâmetros:

sqlcommand: Nome da consulta (sem colchetes) ou um comando SQL.

directsql: Se True, o comando SQL é enviado ao banco de dados diretamente sem análise prévia. O valor padrão é False. Para consultas, a opção aplicada é a definida quando a consulta foi criada.

Exemplo:

Em Basic

      myDatabase.RunSql("INSERT INTO [EmployeeData] VALUES(25, 'Smith', 'John')", DirectSQL := True)
    
Em 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.

warning

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


Sintaxe:

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

Parâmetros:

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.


Exemplo:

Em Basic

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

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

Todas as rotinas ou identificadores do ScriptForge em Basic que possuem o caractere "_" como prefixo são reservadas para uso interno. Elas não devem ser usadas em macros escritas em Basic ou em Python.