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	Retorna uma instância Dictionary com os valores padrão usados para cada campo no conjunto de dados. Os campos ou colunas do conjunto de dados são as chaves do 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 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 an empty string to remove the current filter
      oNewDataset = oDataset.CreateDataset(Filter := "")
      ' Examples of common filters
      oNewDataset = oDataset.CreateDataset(Filter := "[Name] = 'John'")
      oNewDataset = oDataset.CreateDataset(Filter := "[Name] LIKE 'A'")
      ' It is possible to append additional conditions to the current filter
      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:

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:

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.

Serviço SFDatabases.Database