Conteúdo

# 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 LibreOffice, existem cinco tipos de modos de isolamento de transações, conforme definido no grupo de constantes com.sun.star.sdbc.TransactionIsolation:

Constante | Valor | Interpretação
--- | --- | ---
NONE | 0 | O tratamento de transações está desativado e a base de dados está configurada no modo de confirmação automática predefinido.
READ_UNCOMMITTED | 1 | Podem ocorrer leituras incorretas, leituras não repetíveis e leituras fantasmas. Se uma linha for alterada por uma transação, outra transação poderá ler essas alterações, mesmo que estas ainda não tenham sido confirmadas.
READ_COMMITTED | 2 | As leituras incorretas são evitadas; no entanto, podem ocorrer leituras não repetíveis e leituras fantasmas. Este nível impede que sejam lidas linhas com alterações não confirmadas.
REPEATABLE_READ | 4 | As leituras incorretas e as leituras não repetíveis são evitadas. No entanto, podem ocorrer leituras fantasmas. Além de impedir que dados não confirmados sejam lidos, também evita que duas operações de leitura na mesma transação devolvam resultados diferentes.
SERIALIZABLE | 8 | São evitadas as leituras incorretas, as leituras não repetíveis e as leituras fantasmas. Para além das restrições do nível anterior, garante também que o conjunto de registos que correspondem a uma cláusula WHERE permaneça inalterado no âmbito da mesma transação.

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

### Sintaxe:

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.

### Parâmetros:

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.

### Exemplo:

##### Em Basic

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

##### Em Python

          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:

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

##### Em Python

          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

Nome | Apenas leitura | Tipo | Descrição
--- | --- | --- | ---
Queries | Sim | Matriz de cadeias de caracteres | A lista de consultas guardadas.
Tables | Sim | Matriz de cadeias de caracteres | A lista de tabelas armazenadas.
XConnection | Sim | XConnection | O objeto UNO que representa a ligação atual à base de dados.
XMetaData | Sim | XDatabaseMetaData | O objeto UNO que representa os metadados que descrevem os atributos do sistema de base de dados.

Lista de métodos do serviço de base de dados
CloseDatabase Commit CreateDataset DAvg DCount DMin | DMax DSum DLookup GetRows OpenFormDocument OpenQuery | OpenSql OpenTable Rollback RunSql SetTransactionMode

## CloseDatabase

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

### Sintaxe:

db.CloseDatabase()

### Exemplo:

        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.

### Sintaxe:

db.Commit()

### Exemplo:

##### Em Basic

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

##### Em Python

          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.

### Sintaxe:

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

### Parâmetros:

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 LibreOffice (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».

### Exemplo:

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

##### Em Basic

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

##### Em Python

          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.

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

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.

### Exemplo:

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

##### Em Basic

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

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

### Sintaxe:

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

### Parâmetros:

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.

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

### Sintaxe:

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

### Parâmetros:

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.

### Exemplo:

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

##### Em Basic

          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)

##### Em Python

          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.

### Sintaxe:

svc.OpenFormDocument(formdocument: str): svc

### Parâmetros:

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

### Exemplo:

##### Em Basic

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

##### Em Python

        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.

### Sintaxe:

db.OpenQuery(queryname: str): obj

### Parâmetros:

queryname: O nome de uma consulta existente, expresso como uma cadeia de caracteres (String) que distingue 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 «Data View» com os resultados e devolve uma instância do serviço Datasheet.

### Sintaxe:

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

### Parâmetros:

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

### 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 «Data View» da tabela especificada e devolve uma instância do serviço Datasheet.

### Sintaxe:

db.OpenTable(tablename: str): obj

### Parâmetros:

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

### Exemplo:

##### Em Basic

          myDatabase.OpenTable("MyTable")

##### Em Python

          myDatabase.OpenTable("MyTable")

## Rollback

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

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

### Sintaxe:

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

### Parâmetros:

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.

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

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.

### Sintaxe:

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

### Parâmetros:

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

### Exemplo:

##### Em Basic

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

##### Em Python

          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.

Tópicos relacionados

SFDatabases.Datasheet service

SFDatabases.Dataset service

SFDocuments.Document serviço

SFDocuments.Form service

ScriptForge.UI service

Necessitamos da sua ajuda!