Sumário
Índice 🔎︎

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

- Obter acesso aos dados de tabelas em bancos de dados

- Realizar consultas SELECT e executar funções agregadas.

- Realizar ações baseadas em comandos SQL como INSERT, UPDATE, DELETE, etc.

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.

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.

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.

## Invocação do serviço

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

• 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

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

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 DAvg DCount DMin | DMax DSum DLookup GetRows | OpenQuery OpenSql OpenTable RunSql

## CloseDatabase

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

### Sintaxe:

db.CloseDatabase()

### Exemplo:

        myDatabase.CloseDatabase() ' Basic

        myDatabase.CloseDatabase() # Python

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

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

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

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)

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.

Tópicos relacionados

Serviço SFDatabases.Datasheet service

Serviço SFDocuments.Document

Serviço SFDocuments.Form

Serviço ScriptForge.UI