Serviço SFDatabases.Database

O serviço Database permite aceder a bases de dados incorporadas ou descritas em documentos Base. Este serviço disponibiliza métodos para:

• Aceda aos dados nas tabelas da base de dados.

• Executar consultas SELECT e aplicar funções de agregação.

• Executar instruções SQL como INSERT, UPDATE, DELETE, etc.

Cada instância do serviço Database representa uma única base de dados e permite aceder às suas tabelas, consultas e dados.

Este serviço não permite aceder a formulários ou relatórios no documento Base que contém a base de dados. Para aceder a formulários num documento Base, consulte o método FormDocuments do serviço Base.

Todas as interações entre este serviço e a base de dados são realizadas exclusivamente através de SQL.

As instruções SQL podem ser executadas no modo direto ou indireto. No modo direto, a instrução é enviada para o motor da base de dados sem qualquer verificação ou revisão da sintaxe.

As interfaces disponibilizadas incluem tabelas simples e listas de consultas, bem como acesso aos dados da base de dados.

Para tornar as instruções SQL mais legíveis, pode utilizar parênteses retos «[ ]» para delimitar nomes de tabelas, consultas e campos, em vez de utilizar outros caracteres de delimitação que possam ser exclusivos de determinados Sistemas de Gestão de Bases de Dados Relacionais (RDBMS). No entanto, tenha em atenção que os caracteres de delimitação são obrigatórios neste contexto.

Processamento de transações

Por predefinição, a base de dados processa as transações no modo de confirmação automática, o que significa que é efetuada uma confirmação após cada instrução SQL.

Utilize o método SetTransactionMode para alterar o comportamento predefinido, o que permite efetuar confirmações e reversões manualmente.

Os métodos Commit e Rollback são utilizados para delimitar transações.

No LibreOfficeDev, existem cinco tipos de modos de isolamento de transações, conforme definido no grupo de constantes com.sun.star.sdbc.TransactionIsolation:

Leia a página da Wikipédia sobre Isolamento em sistemas de bases de dados para saber mais sobre a integridade das transações.

Chamada de serviço

Antes de utilizar o serviço Database, é necessário carregar ou importar a biblioteca ScriptForge:

• As macros básicas requerem o carregamento da biblioteca ScriptForge através da seguinte instrução:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Os scripts Python requerem a importação do módulo scriptforge:
from scriptforge import CreateScriptService

Para criar uma instância do serviço Database, pode utilizar o método CreateScriptService:

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

Na sintaxe descrita acima, pode utilizar «SFDatabases.Database» ou simplesmente «Database» como primeiro argumento do método CreateScriptService.

nome do ficheiro: O nome do ficheiro Base. Deve ser expresso utilizando a notação SF_FileSystem.FileNaming.

registrationname: O nome de uma base de dados registada. Se for fornecido filename, este argumento não deve ser utilizado.

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

readonly: Determina se a base de dados será aberta em modo de leitura (Predefinição = True).

utilizador, palavra-passe: Parâmetros de ligação adicionais ao servidor da base de dados.

      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDatabase as Object
      Set myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      ' Executar consultas, instruções SQL, ...
      myDatabase.CloseDatabase()
    

      from scriptforge import CreateScriptService
      myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      # Executar consultas, instruções SQL, ...
      myDatabase.CloseDatabase()
    

Aceder a bases de dados com o Serviço de Interface do Utilizador

Também é possível aceder à base de dados associada a um documento Base utilizando o serviço ScriptForge.UI, conforme ilustrado nos exemplos abaixo:

      Dim myDoc As Object, myDatabase As Object, ui As Object
      Set ui = CreateScriptService("UI")
      Set myDoc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      ' O nome de utilizador e a palavra-passe encontram-se abaixo, caso sejam necessários
      Set myDatabase = myDoc.GetDatabase()
      ' Executar consultas, instruções SQL, ...
      myDatabase.CloseDatabase()
      myDoc.CloseDocument()
    

      ui = CreateScriptService("UI")
      doc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      # O nome de utilizador e a palavra-passe são indicados abaixo, caso sejam necessários
      myDatabase = doc.GetDatabase()
      # Executar consultas, instruções SQL, ...
      myDatabase.CloseDatabase()
      doc.CloseDocument()
    

O método GetDatabase utilizado no exemplo acima faz parte do serviço Base do ScriptForge.

Propriedades

CloseDatabase

Encerra a ligação atual à base de dados.

db.CloseDatabase()

    myDatabase.CloseDatabase() ' Basic
  

    myDatabase.CloseDatabase() # Python
  

Commit

Confirma todas as atualizações efetuadas desde a última chamada de Commit ou Rollback.

Este método é ignorado se os commits forem efetuados automaticamente após cada instrução SQL, ou seja, se a base de dados estiver configurada no modo de auto-commit predefinido.

db.Commit()

      ' Definir o nível de transação REPEATABLE_READ
      myDB.SetTransactionMode(4)
      myDB.RunSql("UPDATE ...")
      myDB.Commit()
      myDB.RunSql("DELETE ...")
      ' Verificar uma condição antes de confirmar
      If bSomeCondition Then
          myDB.Commit()
      Else
          myDB.Rollback()
      End If
      ' Restaurar o modo de confirmação automática
      myDB.SetTransactionMode()
    

      myDB.SetTransactionMode(4)
      myDB.RunSql("UPDATE ...")
      myDB.Commit()
      myDB.RunSql("DELETE ...")
      if some_condition:
          myDB.Commit()
      else:
          myDB.Rollback()
      myDB.SetTransactionMode()
    

CreateDataset

Cria uma instância do serviço Dataset com base numa tabela, numa consulta ou numa instrução SQL SELECT.

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

sqlcommand: Um nome de tabela, um nome de consulta ou uma instrução SQL SELECT válida. Os identificadores podem ser colocados entre parênteses retos. Este argumento distingue maiúsculas de minúsculas.

directsql: Defina este argumento como True para enviar a instrução diretamente para o motor da base de dados sem pré-processamento pelo LibreOfficeDev (Predefinição = False).

filtro: Especifica a condição que os registos devem cumprir para serem incluídos no conjunto de dados devolvido. Este argumento é expresso como uma instrução SQL WHERE, sem a palavra-chave «WHERE».

orderby: Especifica a ordenação do conjunto de dados como uma instrução SQL ORDER BY, sem a palavra-chave «ORDER BY».

Os exemplos seguintes em Basic e Python devolvem um conjunto de dados com os registos de uma tabela denominada «Clientes».

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

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

DAvg, DCount, DMin, DMax, DSum

Calcula a função agregada indicada num campo ou numa expressão pertencente a uma tabela.

Opcionalmente, pode ser especificada uma cláusula SQL WHERE como filtro a aplicar antes da função de agregação.

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

expressão: Uma expressão SQL em que os nomes dos campos estão entre parênteses retos.

nome_da_tabela: O nome de uma tabela (sem parênteses retos).

critérios: Uma cláusula WHERE sem a palavra-chave «WHERE», na qual os nomes dos campos são colocados entre parênteses retos.

O exemplo abaixo parte do princípio de que o ficheiro Employees.odb contém uma tabela denominada EmployeeData.

      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDB as Variant
      Set myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")
      ' Calcula o número de funcionários na tabela
      MsgBox myDB.DCount("[ID]", "EmployeeData")
      ' Devolve a soma de todos os salários da tabela
      MsgBox myDB.DSum("[Salary]", "EmployeeData")
      ' Seguem-se alguns exemplos de como as 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%'")
    

      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 num único registo devolvido por uma cláusula WHERE definida pelo parâmetro Criteria.

Se a consulta devolver vários registos, apenas o primeiro é tido em conta. Utilize o parâmetro OrderClause para determinar a forma como os resultados da consulta são ordenados.

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

expressão: Uma expressão SQL em que os nomes dos campos estão entre parênteses retos.

nome_da_tabela: O nome de uma tabela (sem parênteses retos).

critérios: Uma cláusula WHERE sem a palavra-chave «WHERE», na qual os nomes dos campos são colocados entre parênteses retos.

cláusula de ordenação: Uma cláusula ORDER BY sem as palavras-chave «ORDER BY». Os nomes dos campos devem ser colocados entre parênteses retos.

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

      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, os resultados de uma consulta SELECT ou de uma instrução SQL numa matriz bidimensional. O primeiro índice da matriz corresponde às linhas e o segundo índice refere-se às colunas.

É possível especificar um limite máximo para o número de linhas devolvidas. Opcionalmente, podem ser inseridos nomes de colunas na primeira linha da matriz.

O array devolvido estará vazio se não forem devolvidas quaisquer linhas e os cabeçalhos das colunas não forem obrigatórios.

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

sqlcommand: O nome de uma tabela ou de uma consulta (sem parênteses retos) ou uma instrução SQL SELECT.

directsql: Quando True, o comando SQL é enviado para o motor da base de dados sem análise prévia. O valor predefinido é False. Este argumento é ignorado no caso das tabelas. No caso das consultas, a opção aplicada é aquela definida no momento em que a consulta foi criada.

cabeçalho: Quando True, a primeira linha do array devolvido contém os cabeçalhos das colunas.

maxrows: O número máximo de linhas a devolver. O valor predefinido é zero, o que significa que não há limite para o número de linhas devolvidas.

Seguem-se alguns exemplos de como o método GetRows pode ser utilizado:

      Dim queryResults as Variant
      ' Devolve todas as linhas da tabela com os cabeçalhos das colunas
      queryResults = myDB.GetRows("EmployeeData", Header := True)
      ' Devolve os primeiros 50 registos de colaboradores ordenados pelo campo «FirstName»
      queryResults = myDB.GetRows("SELECT * FROM EmployeeData ORDER BY [FirstName]", MaxRows := 50)
    

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

OpenFormDocument

Abre o documento de formulário especificado no modo normal. Este método devolve uma instância do serviço FormDocument correspondente ao documento de formulário especificado.

Se o documento do formulário já estiver aberto, a janela do documento do formulário é ativada.

Se o documento do formulário especificado não existir, é devolvido Nada.

svc.OpenFormDocument(formdocument: str): svc

formdocument: O nome do FormDocument a abrir, como uma cadeia de caracteres que distingue maiúsculas de minúsculas.

A maioria dos documentos de formulário está armazenada na raiz do documento Base e pode ser aberta simplesmente utilizando os seus nomes, como no exemplo abaixo:

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

Se os documentos de formulário estiverem organizados em pastas, torna-se necessário incluir o nome da pasta para especificar o documento de formulário a abrir, conforme ilustrado no exemplo seguinte:

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

    formDoc = myDB.OpenFormDocument("myFormDocument")
  

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

OpenQuery

Abre a janela «Data View» da consulta especificada e devolve uma instância do serviço Datasheet.

Se não for possível abrir a consulta, é devolvido Nothing.

db.OpenQuery(queryname: str): obj

queryname: O nome de uma consulta existente, expresso como uma cadeia de caracteres (String) que distingue maiúsculas de minúsculas.

      myDatabase.OpenQuery("MyQuery")
    

      myDatabase.OpenQuery("MyQuery")
    

OpenSql

Executa um comando SQL SELECT, abre uma janela «Data View» com os resultados e devolve uma instância do serviço Datasheet.

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

sql: Uma cadeia de caracteres que contém uma instrução SELECT válida em SQL. Os identificadores podem ser colocados entre parênteses retos.

directsql: Quando True, o comando SQL é enviado para o motor da base de dados sem análise prévia (Predefinição = False).

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

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

OpenTable

Abre a janela «Data View» da tabela especificada e devolve uma instância do serviço Datasheet.

db.OpenTable(tablename: str): obj

tablename: O nome de uma tabela existente, expresso como uma cadeia de caracteres (String) que distingue maiúsculas de minúsculas.

      myDatabase.OpenTable("MyTable")
    

      myDatabase.OpenTable("MyTable")
    

Rollback

Anula todas as alterações efetuadas na base de dados desde a última chamada de Commit ou Rollback.

db.Rollback()

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

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

RunSql

Executa uma consulta de ação de uma instrução SQL, como a criação de uma tabela, bem como a inserção, atualização e eliminação de registos.

O método devolve True quando é bem-sucedido.

O método RunSql é rejeitado com uma mensagem de erro caso a base de dados tenha sido previamente aberta no modo de leitura apenas.

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

sqlcommand: Um nome de consulta (sem parênteses retos) ou uma instrução SQL.

directsql: Quando True, o comando SQL é enviado para o motor da base de dados sem análise prévia. (Predefinição = False). No caso das consultas, a opção aplicada é aquela definida no momento em que a consulta foi criada.

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

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

SetTransactionMode

Define o nível de isolamento nas transações da base de dados.

Por predefinição, as bases de dados gerem as transações no modo de confirmação automática, o que significa que um Commit é executado automaticamente após cada instrução SQL.

Utilize este método para determinar manualmente o nível de isolamento das transações. Quando é definido um modo de transação diferente de NONE, o script tem de chamar explicitamente o método Commit para aplicar as alterações à base de dados.

Este método devolve True quando é bem-sucedido.

A alteração do modo de transação encerra todas as instâncias de Dataset criadas a partir da base de dados atual.

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

transactionmode: Especifica o modo de transação. Este argumento deve ser uma das constantes definidas em com.sun.star.sdbc.TransactionIsolation (Predefinição = NONE)

Leia a secção Gestão de transações acima para saber mais sobre os níveis de isolamento de transações utilizados no LibreOfficeDev.

      myDB.SetTransactionMode(com.sun.star.sdbc.TransactionIsolation.REPEATABLE_READ)
      oDataset = myDB.CreateDataset("SELECT ...")
      ' ...
      ' Repor o modo de transação para o valor predefinido
      myDB.SetTransactionMode()
    

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

Todas as rotinas ou identificadores do ScriptForge Basic que tenham o caractere de sublinhado «_» como prefixo estão reservados para uso interno. Não se destinam a ser utilizados em macros do Basic ou em scripts Python.