Sumário

# Serviço SFDatabases.Dataset

O serviço Dataset é usado para representar dados tabulares produzidos por um banco de dados. Com este serviço é possível:

- Navegar e acessar os dados em um conjunto de dados.

- Atualizar, inserir e remover registros em um conjunto de dados.

Atualizar e inserir registros usando o serviço Dataset é mais lento do que usar instruções SQL. Ao atualizar ou inserir grandes quantidades de registros, é recomendado utilizar instruções SQL em vez de utilizar os métodos deste serviço.

## Invocação do serviço

Antes de usar o serviço Dataset 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

O serviço Dataset é invocado usando o método CreateDataset, que pode ser chamado de uma instância do serviço Database ou de outra instância Dataset.

##### Em Basic

O exemplo a seguir cria um Dataset a partir da tabela "Clientes" armazenada em um arquivo de banco de dados.

        oDatabase = CreateScriptService("Database", "C:\MyDatabase.odb")
        oDataset = oDatabase.CreateDataset("Clientes")
        With oDataset
            Do While .MoveNext()
                oValues = .Values()
                ' ...
            Loop
            .CloseDataset()
        End With

Após a criação do Dataset, o registro atual é posicionado antes do primeiro registro.

O exemplo abaixo cria uma instância do serviço Dataset filtrando o conjunto de dados original.

        oNewDataset = oDataset.CreateDataset(Filter := "[City]='New York'")

##### Em Python

        database = CreateScriptService("Database", r"C:\MyDatabase.odb")
        dataset = database.CreateDataset("Clientes")
        while dataset.MoveNext():
            values = dataset.Values
            # ...
        dataset.CloseDataset()

        new_dataset = dataset.CreateDataset(filter = "[Cidade]='São Paulo'")

## Propriedades

Nome | Somente leitura | Tipo | Descrição
--- | --- | --- | ---
BOF | Não | Boolean | Retorna True se a posição atual do registro for anterior ao primeiro registro no conjunto de dados, caso contrário, retorna False. Defina esta propriedade como True para mover o cursor para o início do conjunto de dados. Definir esta propriedade como False é ignorado.
DefaultValues | Sim | Serviço Dictionary | Returna um Dictionary com valores padrão usados em cada campo no dataset. Os campos ou colunas no dataset são as chaves no dicionário. Os tipos de campo do banco de dados são convertidos em seus tipos de dados correspondentes em Basic ou Python. Quando o tipo do campo é indefinido, o valor padrão é Null se o campo for anulável ou Empty caso contrário.
EOF | Não | Boolean | Retorna True se a posição atual do registro for após o último registro no conjunto de dados, caso contrário, retorna False. Defina esta propriedade como True para mover o cursor para o final do conjunto de dados. Definir esta propriedade como False é ignorado.
Fields | Sim | Array | Retorna um Array contendo os nomes de todos os campos do conjunto de dados.
Filter | Sim | String | Retorna o filtro aplicado além das eventuais cláusulas WHERE na instrução SQL inicial. Esta propriedade é expressa como uma cláusula WHERE sem a palavra-chave "WHERE".
OrderBy | Sim | String | Retorna a cláusula de ordenação que substitui a eventual cláusula ORDER BY presente na instrução SQL inicial. Esta propriedade é expressa como uma cláusula ORDER BY sem as palavras-chave "ORDER BY".
ParentDatabase | Sim | Serviço Database | Retorna a instância Database correspondente ao banco de dados pai do conjunto de dados atual.
RowCount | Sim | Long | Retorna o número exato de registros no conjunto de dados. Note que a avaliação desta propriedade implica navegar em todo o conjunto de dados, o que pode ser dispendioso dependendo do tamanho do conjunto de dados.
RowNumber | Sim | Long | Retorna o número do registro atual começando em 1. Retorna 0 se esta propriedade for desconhecida.
Source | Sim | String | Retorna a origem do conjunto de dados. Pode ser um nome de tabela, um nome de consulta ou uma instrução SQL.
SourceType | Sim | String | Retorna a origem do conjunto de dados. Pode ser um dos seguintes valores expressos como uma string: TABLE, QUERY ou SQL.
UpdatableFields | Sim | Array | Retorna um Array contendo os nomes dos campos do conjunto de dados que são atualizáveis.
Values | Sim | Array | Retorna um Dictionary contendo os pares (nome do campo: valor) do registro atual no conjunto de dados.
XRowSet | Sim | Objeto UNO | Retorna o objeto UNO com.sun.star.sdb.RowSet que representa o conjunto de dados.

Lista de Métodos no Serviço Dataset
CloseDataset CreateDataset Delete ExportValueToFile GetRows | GetValue Insert MoveFirst MoveLast | MoveNext MovePrevious Reload Update

## CloseDataset

Fecha o conjunto de dados atual. Este método retorna True quando bem-sucedido.

Recomenda-se fechar o conjunto de dados após seu uso para liberar recursos.

### Sintaxe:

svc.CloseDataset(): bool

### Exemplo:

##### Em Basic

          oDataset = oDatabase.CreateDataset("MyTable")
          ' ...
          oDataset.CloseDataset()

##### Em Python

          dataset = database.CreateDataset("MyTable")
          # ...
          dataset.CloseDataset()

## CreateDataset

Retorna uma instância do serviço Dataset de um conjunto de dados existente, aplicando o filtro especificado e as instruções ORDER BY.

### Sintaxe:

svc.CreateDataset(opt filter: str, opt orderby: str): svc

### Parâmetros:

filter: especifica a condição que os registros devem atender para serem incluídos no conjunto de dados retornado. Este argumento é expresso como uma instrução SQL WHERE sem a palavra-chave "WHERE". Se este argumento não for especificado, então o filtro usado no conjunto de dados atual será aplicado, caso contrário, o filtro atual será substituído por este argumento.

orderby: especifica a ordem do conjunto de dados como uma instrução SQL ORDER BY sem a palavra-chave "ORDER BY". Se este argumento não for especificado, então a ordem de classificação usada no conjunto de dados atual será aplicada; caso contrário, a ordem de classificação atual será substituída por este argumento.

### Exemplo:

##### Em Basic

          ' Use uma string vazia para remover o filtro atual
          oNewDataset = oDataset.CreateDataset(Filter := "")
          ' Exemplos de filtros comuns
          oNewDataset = oDataset.CreateDataset(Filter := "[Name] = 'John'")
          oNewDataset = oDataset.CreateDataset(Filter := "[Name] LIKE 'A'")
          É possível acrescentar condições adicionais ao filtro atual
          oNewDataset = oDataset.CreateDataset(Filter := "(" & oDataset.Filter & ") AND [Name] LIKE 'A'")

##### Em Python

          new_dataset = dataset.CreateDataset(filter = "")
          new_dataset = dataset.CreateDataset(filter = "[Nome] = 'John'")
          new_dataset = dataset.CreateDataset(filter = "[Nome] LIKE 'A'")
          new_dataset = dataset.CreateDataset(filter = f"({dataset.Filter}) AND [Nome] LIKE 'A'")

## Delete

Exclui o registro atual do conjunto de dados. Este método retorna True quando bem-sucedido.

Após esta operação o cursor é posicionado no registro imediatamente após o registro excluído. Se o registro excluído for o último do conjunto de dados, então o cursor é posicionado depois dele e a propriedade EOF retorna True.

### Sintaxe:

svc.Delete(): bool

### Exemplo:

##### Em Basic

          oDataset.Delete()

##### Em Python

          dataset.Delete()

## ExportValueToFile

Exporta o valor de um campo binário do registro atual para o arquivo especificado.

Se o campo especificado não for binário ou não contiver dados, o arquivo de saída não será criado.

### Sintaxe:

svc.ExportValueToFile(fieldname: str, filename: str, overwrite: bool): bool

### Parâmetros:

fieldname: o nome do campo binário a ser exportado, como uma string sensível à caixa.

filename: O caminho completo para o arquivo a ser criado usando a notação definida na propriedade FileSystem.FileNaming.

overwrite: Defina este argumento como True para permitir que o arquivo de destino seja sobrescrito (Padrão = False).

### Exemplo:

No exemplo abaixo o conjunto de dados contém um campo denominado “Imagem” que deverá ser exportado para um arquivo de imagem.

##### Em Basic

          oDataset.ExportValueToFile("Imagem", "C:\minha_imagem.png", True)

##### Em Python

          dataset.ExportValueToFile("Imagem", r"C:\minha_imagem.png", True)

## GetRows

Retorna o conteúdo do conjunto de dados em uma matriz bidimensional, começando no primeiro registro após o registro atual.

Após a execução, o cursor é posicionado na última linha lida ou após o último registro do conjunto de dados, neste caso a propriedade EOF retorna True.

Este método pode ser usado para ler dados do conjunto de dados em blocos, cujo tamanho é definido pelo argumento maxrows.

A matriz retornada sempre terá duas dimensões, mesmo que o conjunto de dados contenha uma única coluna e um único registro.

### Sintaxe:

svc.GetRows(header: bool, maxrows: int): any

### Parâmetros:

header: Defina este argumento como True para fazer com que a primeira entrada no Array contenha os cabeçalhos das colunas (Padrão = False).

maxrows: Define o número máximo de registros a serem retornados. Se o número de registros existentes for menor que maxrows, então o tamanho do array retornado será igual ao número de registros restantes no conjunto de dados. Deixe este argumento em branco ou defina-o como zero para retornar todas as linhas do conjunto de dados (padrão = 0)

### Exemplo:

O exemplo a seguir lê um conjunto de dados em blocos de 100 linhas até que todo o conjunto de dados tenha sido lido.

##### Em Basic

          Dim arrChunk As Variant, lMaxRows As Long
          lMaxRows = 100
          Do
              arrChunk = oDataset.GetRows(MaxRows := lMaxRows)
              If UBound(arrChunk, 1) >= 0 Then
                  ' ...
              End If
          Loop Until UBound(arrChunk, 1) < lMaxRows - 1

##### Em Python

          max_rows = 100
          chunk = dataset.GetRows(maxrows = max_rows)
          while len(chunk) > 0:
              # ...
              chunk = dataset.GetRows(maxrows = max_rows)

## GetValue

Retorna o valor do campo especificado do registro atual do conjunto de dados.

Se o campo especificado for binário, seu comprimento será retornado.

### Sintaxe:

svc.GetValue(fieldname: str): any

### Parâmetros:

fieldname: O nome do campo a ser retornado, como uma string sensível à caixa.

### Exemplo:

##### Em Basic

          currId = oDataset.GetValue(FieldName := "ID")

##### Em Python

          curr_id = dataset.GetValue(fieldname = "ID")

## Insert

Insere um novo registro no final do conjunto de dados e inicializa seus campos com os valores especificados.

Se a chave primária do conjunto de dados for um valor automático, este método retornará o valor da chave primária do novo registro. Caso contrário, o método retornará 0 (quando bem-sucedido) ou -1 (quando não for bem-sucedido).

Os campos atualizáveis com valores não especificados são inicializados com seus valores padrão.

Se o campo especificado for binário, seu comprimento será retornado.

### Sintaxe:

svc.Insert(pvargs: any): int

### Parâmetros:

pvargs: Uma instância Dictionary contendo pares de nomes de campos e seus respectivos valores. Alternativamente, um número par de argumentos pode ser especificado alternando nomes de campos (como uma String) e seus valores.

### Exemplo:

##### Em Basic

Considere uma tabela chamada "Clientes" com 4 campos: "ID" (BigInt, valor automático e chave primária), "Nome" (VarChar), "Idade" (Integer), "Cidade" (VarChar).

O exemplo abaixo insere um novo registro neste conjunto de dados usando um objeto Dictionary.

          oDataset = oDatabase.CreateDataset("Clientes")
          oNewData = CreateScriptService("Dictionary")
          oNewData.Add("Nome", "João")
          oNewData.Add("Idade", 50)
          oNewData.Add("Cidade", "Curitiba")
          lNewID = oDataset.Insert(oNewData)

O mesmo resultado pode ser alcançado passando todos os pares de campos e valores como argumentos:

          oDataset.Insert("Nome", "João", "Idade", 50, "Cidade", "Curitiba")

##### Em Python

          dataset = database.CreateDataset("Clientes")
          new_data = {"Nome": "João", "Idade": 30, "Cidade": "Curitiba"}
          new_id = dataset.Insert(new_data)

As seguintes chamadas são aceitas em Python:

          dataset.Insert("Nome", "João", "Idade", 50, "Cidade", "Curitiba")
          dataset.Insert(Nome = "João", Idade = 50, Cidade = "Curitiba")

## MoveFirst / MoveLast

Move o cursor do conjunto de dados para o primeiro (com MoveFirst) ou para o último (com MoveLast) registro.

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

Os registros excluídos são ignorados por este método.

### Sintaxe:

svc.MoveFirst(): bool

svc.MoveLast(): bool

### Exemplo:

##### Em Basic

          oDataset.MoveFirst()

##### Em Python

          dataset.MoveFirst()

## MoveNext / MovePrevious

Move o cursor do conjunto de dados para frente (com MoveNext) ou para trás (com MovePrevious) por um determinado número de registros.

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

Os registros excluídos são ignorados por este método.

### Sintaxe:

svc.MoveNext(offset: int = 1): bool

svc.MovePrevious(offset: int = 1): bool

### Parâmetros:

offset: Número de registros pelos quais o cursor deve ser movido para frente ou para trás. Este argumento pode ser um valor negativo (Padrão = 1).

### Exemplo:

##### Em Basic

          oDataset.MoveNext()
          oDataset.MoveNext(5)

##### Em Python

          dataset.MoveNext()
          dataset.MoveNext(5)

## Reload

Recarrega o conjunto de dados a partir do banco de dados. As propriedades Filter e OrderBy podem ser definidas ao chamar este método.

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

Recarregar o conjunto de dados é útil quando registros foram inseridos ou excluídos do banco de dados. Observe que os métodos CreateDataset e Reload executam funções semelhantes, porém Reload reutiliza a mesma instância da classe Dataset.

### Sintaxe:

svc.Reload(opt filter: str, opt orderby: str): bool

### Parâmetros:

filter: especifica a condição que os registros devem atender para serem incluídos no conjunto de dados retornado. Este argumento é expresso como uma instrução SQL WHERE sem a palavra-chave "WHERE". Se este argumento não for especificado, então o filtro usado no conjunto de dados atual será aplicado, caso contrário, o filtro atual será substituído por este argumento.

orderby: especifica a ordem do conjunto de dados como uma instrução SQL ORDER BY sem a palavra-chave "ORDER BY". Se este argumento não for especificado, então a ordem de classificação usada no conjunto de dados atual será aplicada; caso contrário, a ordem de classificação atual será substituída por este argumento.

### Exemplo:

##### Em Basic

          oDataset.Reload()
          oDataset.Reload(Filter := "[Nome] = 'João'", OrderBy := "Idade")

##### Em Python

          dataset.Reload()
          dataset.Reload(Filter = "[Nome] = 'João'", OrderBy = "Idade")

## Update

Atualize os valores dos campos especificados no registro atual.

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

### Sintaxe:

svc.Update(pvargs: any): bool

### Parâmetros:

pvargs: Uma instância Dictionary contendo pares de nomes de campos e seus respectivos valores. Alternativamente, um número par de argumentos pode ser especificado alternando nomes de campos (como uma String) e seus valores.

### Exemplo:

##### Em Basic

O exemplo abaixo atualiza o registro atual usando um objeto Dictionary.

          oNewValues = CreateScriptService("Dictionary")
          oNewValues.Add("Idade", 51)
          oNewValues.Add("Cidade", "Florianópolis")
          oDataset.Update(oNewValues)

O mesmo resultado pode ser alcançado passando todos os pares de campos e valores como argumentos:

          oDataset.Update("Idade", 51, "Cidade", "Florianópolis")

##### Em Python

          new_values = {"Idade": 51, "Cidade": "Florianópolis"}
          dataset.Update(new_values)

          dataset.Update("Idade", 51, "Cidade", "Florianópolis")
          dataset.Update(Idade = 51, Cidade = "Florianópolis")

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