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 banco de dados único e permite acesso a suas tabelas, consultas e dados. Este serviço não fornece acesso aos formulários e relatórios no documento 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 os comandos SQL mais legíveis você pode usar colchetes opcionais em volta dos nomes de tabelas, consultas e campos em vez de usar outros caracteres que podem ser exclusivos para certos Sistemas de Gerenciamento de Bancos de Dados (SGBDs).


Invocação do serviço

Sintaxe:

O trecho de código abaixo mostra como acessar qualquer banco de dados com o serviço Database.


        Dim myDatabase As Object
        Set myDatabase = CreateScriptService("SFDatabases.Database", [FileName], [RegistrationName], [ReadOnly], [User, [Password]])
        ' ... Executar consultas, comandos SQL, etc...
        myDatabase.CloseDatabase()
    

Parâmetros:

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

RegistrationName: Nome do banco de dados registrado. Se um nome de arquivo 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.

note

Este serviço é totalmente compatível com as linguagens Basic e Python. Todos os exemplos são descritos usando a linguagem de programação Basic e podem ser facilmente convertidos para Python.


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 apresentado no exemplo abaixo:


        Dim myDoc As Object, myDatabase As Object, ui As Object
        Set ui = CreateScriptService("UI")
        Set myDoc = ui.OpenBaseDocument("myDb.odb")
        ' Nome de usuário e senha são informados abaixo, se necessário
        Set myDatabase = myDoc.GetDatabase()
        ' ... Executar consultas, comandos SQL, etc...
        myDoc.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
DAvg
DCount

DMin
DMax
DSum

DLookup
GetRows
RunSql


CloseDatabase

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

Sintaxe:


       myDatabase.CloseDatabase()
     

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:


        myDatabase.DAvg(Expression As String, TableName As String, [Criteria As String]) As Variant
    

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.


      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDB as Variant
      Set myDB = CreateScriptService("Database", "~/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%'")
    

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:


        myDatabase.DLookup(Expression As String, TableName As String, [Criteria As String], [OrderClause As String]) As Variant
    

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:


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

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:


        myDatabase.GetRows(SQLCommand As String, [DirectSQL As Boolean], [Header As Boolean], [MaxRows As Long]) As Variant
    

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:


        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)
    

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:


        myDatabase.RunSql(SQLCommand As String, [DirectSQL As Boolean]) As Boolean
    

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:


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

Todas as rotinas básicas ou identificadores do ScriptForge que possuem o caractere "_" como prefixo são reservados apenas para uso interno. Elas não devem ser usadas em macros Basic.


♥ Doe para nosso projeto! ♥