SFDatabases.Dataset service

O serviço Dataset é utilizado para representar dados tabulares produzidos por uma base de dados. Com este serviço, é possível:

Navegar e aceder aos dados de um conjunto de dados.
Atualizar, inserir e eliminar registos num conjunto de dados.

A atualização e a inserção de registos através do serviço Dataset são mais lentas do que utilizando instruções SQL. Ao atualizar ou inserir grandes quantidades de registos, recomenda-se a utilização de instruções SQL em vez dos métodos deste serviço.

Chamada de serviço

Antes de utilizar o serviço Dataset, é 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

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

Em Basic

O exemplo seguinte cria um Dataset a partir da tabela «Clientes» armazenada num ficheiro de base 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 registo atual é posicionado antes do primeiro registo.

O exemplo abaixo cria uma instância de 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 = "[City]='New York'")

Propriedades

Nome	Apenas leitura	Tipo	Descrição
BOF	Não	Boolean	Devolve True se a posição atual do registo estiver antes do primeiro registo do conjunto de dados; caso contrário, devolve False. Defina esta propriedade como True para deslocar o cursor para o início do conjunto de dados. A definição desta propriedade como False é ignorada.
DefaultValues	Sim	Serviço Dicionário	Devolve um Dicionário com os valores predefinidos utilizados para cada campo do conjunto de dados. Os campos ou colunas do conjunto de dados correspondem às chaves do dicionário. Os tipos de campo da base de dados são convertidos para os respetivos tipos de dados Basic/Python. Quando o tipo de campo não está definido, o valor por predefinição é Null, se o campo for nulo, ou Empty.
EOF	Não	Boolean	Devolve True se a posição atual do registo estiver após o último registo do conjunto de dados; caso contrário, devolve False. Defina esta propriedade como True para deslocar o cursor para o final do conjunto de dados. A definição desta propriedade como False é ignorada.
Fields	Sim	Array	Devolve um Array que contém os nomes de todos os campos do conjunto de dados.
Filter	Sim	String	Devolve o filtro aplicado, para além das eventuais cláusulas WHERE presentes na instrução SQL inicial. Esta propriedade é expressa como uma cláusula WHERE sem a palavra-chave «WHERE».
OrderBy	Sim	String	Devolve 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 Base de dados	Devolve a instância Database correspondente à base de dados principal do conjunto de dados atual.
RowCount	Sim	Long	Devolve o número exato de registos no conjunto de dados. Note-se que a avaliação desta propriedade implica percorrer todo o conjunto de dados, o que pode ser dispendioso, dependendo do tamanho do conjunto de dados.
RowNumber	Sim	Long	Devolve o número do registo atual, começando em 1. Devolve 0 se esta propriedade for desconhecida.
Source	Sim	String	Devolve a fonte do conjunto de dados. Pode ser um nome de tabela, um nome de consulta ou uma instrução SQL.
SourceType	Sim	String	Devolve a origem do conjunto de dados. Pode ser um dos seguintes valores de cadeia de caracteres: TABLE, QUERY ou SQL.
UpdatableFields	Sim	Array	Devolve um Array que contém os nomes dos campos do conjunto de dados que podem ser atualizados.
Values	Sim	Array	Devolve um Dicionário que contém os pares (nome do campo: valor) do registo atual no conjunto de dados.
XRowSet	Sim	UNO objeto	Devolve o objeto UNO com.sun.star.sdb.RowSet que representa o conjunto de dados.

Lista de métodos do serviço de conjuntos de dados
CloseDataset CreateDataset Delete ExportValueToFile GetRows	GetValue Insert MoveFirst MoveLast	MoveNext MovePrevious Reload Update

CloseDataset

Fecha o conjunto de dados atual. Este método devolve True em caso de sucesso.

Recomenda-se fechar o conjunto de dados após a sua utilização, para libertar recursos.

Sintaxe:

svc.CloseDataset(): bool

Exemplo:

Em Basic


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

Em Python


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

CreateDataset

Devolve uma instância do serviço Dataset a partir 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:

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». Se este argumento não for especificado, é aplicado o filtro utilizado no conjunto de dados atual; caso contrário, o filtro atual é substituído por este argumento.

orderby: Especifica a ordenação do conjunto de dados como uma instrução SQL ORDER BY, sem a palavra-chave «ORDER BY». Se este argumento não for especificado, é aplicada a ordem de ordenação utilizada no conjunto de dados atual; caso contrário, a ordem de ordenação atual é substituída por este argumento.

Exemplo:

Em Basic


      ' Utilize uma cadeia de caracteres vazia para remover o filtro atual
      oNewDataset = oDataset.CreateDataset(Filter := "")
      ' Exemplos de filtros comuns
      ' Exemplos de filtros comuns
      oNewDataset = oDataset.CreateDataset(Filter := "[Name] LIKE 'A'")
      ' É possível adicionar 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 = "[Name] = 'John'")
      new_dataset = dataset.CreateDataset(filter = "[Name] LIKE 'A'")
      new_dataset = dataset.CreateDataset(filter = f"({dataset.Filter}) AND [Name] LIKE 'A'")

Delete

Elimina o registo atual do conjunto de dados. Este método devolve True em caso de sucesso.

Após esta operação, o cursor é posicionado no registo imediatamente a seguir ao registo eliminado. Se o registo eliminado for o último do conjunto de dados, o cursor é posicionado a seguir a este e a propriedade EOF devolve True.

Sintaxe:

svc.Delete(): bool

Exemplo:

Em Basic


      oDataset.Delete()

Em Python


      dataset.Delete()

ExportValueToFile

Exporta o valor de um campo binário do registo atual para o ficheiro especificado.

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

Sintaxe:

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

Parâmetros:

fieldname: O nome do campo binário a exportar, como uma cadeia de caracteres que distingue maiúsculas de minúsculas.

nome do ficheiro: O caminho completo para o ficheiro a ser criado, utilizando a notação definida na propriedade FileSystem.FileNaming.

sobrescrever: Defina este argumento como True para permitir que o ficheiro de destino seja sobrescrito (Predefinição = False).

Exemplo:

No exemplo abaixo, o conjunto de dados contém um campo denominado «Picture» que deve ser exportado para um ficheiro de imagem.

Em Basic


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

Em Python


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

GetRows

Devolve o conteúdo do conjunto de dados numa matriz bidimensional, a partir do primeiro registo seguinte ao registo atual.

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

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

O array devolvido terá sempre duas dimensões, mesmo que o conjunto de dados contenha uma única coluna e um único registo.

Sintaxe:

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

Parâmetros:

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

maxrows: Define o número máximo de registos a devolver. Se o número de registos existentes for inferior a maxrows, o tamanho do array devolvido será igual ao número de registos restantes no conjunto de dados. Deixe este argumento em branco ou defina-o como zero para devolver todas as linhas do conjunto de dados (Predefinição = 0)

Exemplo:

O exemplo seguinte 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

Devolve o valor do campo especificado do registo atual do conjunto de dados.

Se o campo especificado for binário, é devolvido o seu comprimento.

Sintaxe:

svc.GetValue(fieldname: str): any

Parâmetros:

fieldname: O nome do campo a ser devolvido, como uma cadeia de caracteres que distingue maiúsculas de minúsculas.

Exemplo:

Em Basic


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

Em Python


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

Insert

Inserir um novo registo no final do conjunto de dados e inicializar os seus campos com os valores especificados.

Se a chave primária do conjunto de dados for um valor automático, este método devolve o valor da chave primária do novo registo. Caso contrário, o método devolve 0 (em caso de sucesso) ou -1 (em caso de falha).

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

Se o campo especificado for binário, é devolvido o seu comprimento.

Sintaxe:

svc.Insert(pvargs: any): int

Parâmetros:

pvargs: Um Dicionário que contém pares de nomes de campos e os respetivos valores. Em alternativa, pode especificar-se um número par de argumentos, alternando entre nomes de campos (na forma de uma String) e os respetivos valores.

Exemplo:

Em Basic

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

O exemplo abaixo insere um novo registo neste conjunto de dados utilizando um Dicionário.


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

É possível obter o mesmo resultado passando todos os pares de campos e valores como argumentos:


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

Em Python


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

As seguintes chamadas são aceites em Python:


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

MoveFirst / MoveLast

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

Este método devolve True quando é bem-sucedido.

Os registos eliminados 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

Avança o cursor do conjunto de dados (com MoveNext) ou recua-o (com MovePrevious) um determinado número de registos.

Este método devolve True quando é bem-sucedido.

Os registos eliminados são ignorados por este método.

Sintaxe:

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

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

Parâmetros:

offset: O número de registos em que o cursor deve ser deslocado para a frente ou para trás. Este argumento pode ser um valor negativo (valor predefinido = 1).

Exemplo:

Em Basic


      oDataset.MoveNext()
      oDataset.MoveNext(5)

Em Python


      dataset.MoveNext()
      dataset.MoveNext(5)

Reload

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

Este método devolve True quando é bem-sucedido.

Recarregar o conjunto de dados é útil quando foram inseridos ou eliminados registos da base de dados. Note-se que os métodos CreateDataset e Reload desempenham funções semelhantes; no entanto, o método 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

Atualizar os valores dos campos especificados no registo atual.

Este método devolve True quando é bem-sucedido.

Sintaxe:

svc.Update(pvargs: any): bool

Parâmetros:

Exemplo:

Em Basic

O exemplo abaixo atualiza o registo atual utilizando um Dicionário.


      oNewValues = CreateScriptService("Dictionary")
      oNewValues.Add("Idade", 51)
      oNewValues.Add("Cidade", "Nova Iorque")
      oDataset.Update(oNewValues)

É possível obter o mesmo resultado passando todos os pares de campos e valores como argumentos:


      oDataset.Update("Idade", 51, "Cidade", "Nova Iorque")

Em Python


      new_values = {"Idade": 51, "Cidade": "Nova Iorque"}
      dataset.Update(new_values)


      dataset.Update("Idade", 51, "Cidade", "Nova Iorque")
      dataset.Update(Idade = 51, Cidade = "Nova Iorque")

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.

Serviço SFDatabases.Database