Serviço SFDatabases.Dataset

Conteúdo

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

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

          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:

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

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.

Tópicos relacionados

Serviço SFDatabases.Database

Necessitamos da sua ajuda!