Contenuto

# Servizio SFDatabases.Dataset

Il servizio Dataset è usato per rappresentare in formato tabulare i dati prodotti da un database. Con questo servizio è possibile:

- Navigare attraverso e accedere ai dati di un insieme di dati.

- Aggiornare, inserire ed eliminare record in un insieme di dati.

L'aggiornamento e l'inserimento di record usando il servizio Dataset è più lento rispetto all'uso di istruzioni SQL. Quando si aggiornano o inseriscono quantità elevate di record, è raccomandato l'uso di istruzioni SQL invece dei metodi di questo servizio.

## Invocazione del servizio

Prima di usare il servizio Dataset è necessario caricare o importare le librerie ScriptForge:

• Le macro in Basic richiedono il caricamento della libreria ScriptForge usando la seguente istruzione:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Gli script in Python richiedono un'importazione dal modulo scriptforge:
from scriptforge import CreateScriptService

Il servizio Dataset viene invocato usando il metodo CreateDataset, che può essere chiamato sia da un'istanza del servizio Database, sia da un'altra istanza di Dataset.

##### In Basic

L'esempio seguente crea un Dataset dalla tabella "Clienti" memorizzata in un file di database.

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

Subito dopo la creazione del Dataset, il record corrente è posizionato prima del primo record.

L'esempio sottostante crea un'istanza di Dataset filtrando l'insieme di dati originario.

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

##### In Python

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

        new_dataset = dataset.CreateDataset(filter = "[City]='New York'")

## Proprietà

Nome | Sola lettura | Tipo | Descrizione
--- | --- | --- | ---
BOF | No | Boolean | Restituisce True se la posizione del record corrente si trova prima del primo record dell'insieme di dati, altrimenti restituisce False. Impostare questa proprietà a True per spostare il cursore all'inizio dell'insieme di dati. Impostando questa proprietà a False sarà ignorata.
DefaultValues | Sì | Servizio Dictionary | Restituisce un oggetto Dictionary contenente i valori predefiniti usati per ciascun campo dell'insieme di dati. I campi o le colonne dell'insieme di dati sono le chiavi del dizionario. I tipi di campo del database sono convertiti nei corrispondenti tipi di dati di Basic/Python. Se il tipo di campo non è definito, il valore predefinito è Null quando il campo ammette questo valore, oppure Empty.
EOF | No | Boolean | Restituisce True se la posizione del record corrente è successiva all'ultimo record dell'insieme di dati, altrimenti restituisce False. Impostare questa proprietà a True per spostare il cursore alla fine dell'insieme di dati. Impostando questa proprietà a False sarà ignorata.
Fields | Sì | Array | Restituisce una matrice (Array) contenente i nomi di tutti i campi dell'insieme di dati.
Filter | Sì | String | Restituisce il filtro applicato in aggiunta alle eventuali clausole WHERE dell'istruzione SQL iniziale. Questa proprietà viene espressa come una clausola WHERE priva della parola chiave "WHERE".
OrderBy | Sì | String | Restituisce la clausola di ordinamento che sostituisce l'eventuale clausola ORDER BY presente nell'istruzione SQL iniziale. Questa proprietà viene espressa come una clausola ORDER BY priva delle parole chiave "ORDER BY".
ParentDatabase | Sì | Servizio Database | Restituisce l'istanza di Database corrispondente al database dal quale è stato generato l'insieme di dati corrente.
RowCount | Sì | Long | Restituisce il numero esatto di record nell'insieme di dati. Da notare che il calcolo di questa proprietà implica l'analisi dell'intero insieme di dati, il che può essere dispendioso in base alla grandezza dell'insieme di dati.
RowNumber | Sì | Long | Restituisce il numero del record corrente a partire da 1. Restituisce 0 se questa proprietà non è nota.
Source | Sì | String | Restituisce la fonte dell'insieme di dati. Può essere il nome di una tabella, il nome di una ricerca o un'istruzione SQL.
SourceType | Sì | String | Restituisce la fonte dell'insieme di dati. Può essere solamente una stringa con i seguenti valori: TABLE, QUERY o SQL.
UpdatableFields | Sì | Array | Restituisce una matrice (Array) contenente i nomi dei campi dell'insieme di dati che possono essere aggiornati.
Values | Sì | Array | Restituisce un oggetto Dictionary contenente le coppie (nome campo: valore) del record corrente dell'insieme di dati.
XRowSet | Sì | Oggetto UNO | Restituisce l'oggetto UNO com.sun.star.sdb.RowSet che rappresenta l'insieme di dati.

Elenco dei metodi del servizio Dataset
CloseDataset CreateDataset Delete ExportValueToFile GetRows | GetValue Insert MoveFirst MoveLast | MoveNext MovePrevious Reload Update

## CloseDataset

Chiude l'insieme di dati corrente. Questo metodo restituisce True se eseguito correttamente.

Si raccomanda di chiudere l'insieme di dati dopo il suo utilizzo, in modo da liberare risorse.

### Sintassi:

svc.CloseDataset(): bool

### Esempio:

##### In Basic

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

##### In Python

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

## CreateDataset

Restituisce un'istanza del servizio Dataset a partire da un insieme di dati esistente al quale applica le istruzioni di filtro e ordinamento specificate.

### Sintassi:

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

### Parametri:

filter: specifica la condizione che i record devono rispettare per essere compresi nell'insieme di dati restituito. Questo argomento viene espresso come un'istruzione WHERE di SQL priva della parola chiave "WHERE". Se questo argomento non è specificato, viene applicato il filtro usato nell'insieme di dati corrente, altrimenti il filtro corrente è sostituito da questo argomento.

orderby: specifica l'ordinamento dell'insieme di dati come un'istruzione ORDER BY di SQL priva delle parole chiave "ORDER BY". Se questo argomento non è specificato, viene applicato l'ordinamento corrente dell'insieme di dati, altrimenti l'ordinamento corrente è sostituito da questo argomento.

### Esempio:

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

##### In 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 il record corrente dall'insieme di dati. Questo metodo restituisce True se eseguito correttamente.

Dopo questa operazione il cursore si posiziona sul record immediatamente successivo a quello eliminato. Se il record eliminato è l'ultimo dell'insieme di dati, il cursore si posiziona subito dopo e la proprietà EOF restituisce True.

### Sintassi:

svc.Delete(): bool

### Esempio:

##### In Basic

          oDataset.Delete()

##### In Python

          dataset.Delete()

## ExportValueToFile

Esporta il valore di un campo binario del record corrente nel file specificato.

Se il campo specificato non è binario o se non contiene dati, il file di output non viene creato.

### Sintassi:

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

### Parametri:

fieldname: il nome del campo binario da esportare, in formato di stringa che distingue tra lettere minuscole e maiuscole.

filename: il percorso completo del file da creare indicato usando la notazione definita nella proprietà FileSystem.FileNaming.

overwrite: impostare questo argomento a True per consentire che il file di destinazione possa essere sovrascritto (predefinito = False).

### Esempio:

Nell'esempio sottostante l'insieme di dati contiene un campo denominato "Picture" che deve essere esportato in un file immagine.

##### In Basic

          oDataset.ExportValueToFile("Picture", "C:\mia_immagine.png", True)

##### In Python

          dataset.ExportValueToFile("Picture", r"C:\mia_immagine.png", True)

## GetRows

Restituisce i contenuti dell'insieme di dati in una matrice bidimensionale, a partire dal primo record successivo a quello corrente.

Dopo l'esecuzione, il cursore si posizione sull'ultima riga letta o dopo l'ultimo record dell'insieme di dati, in tal caso la proprietà EOF restituisce True.

Questo metodo può essere usato per leggere un insieme di dati a spezzoni, le cui dimensioni sono definite dall'argomento maxrows.

La matrice restituita avrà sempre due dimensioni, anche quando l'insieme di dati contiene un'unica colonna e un singolo record.

### Sintassi:

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

### Parametri:

header: impostare questo argomento a True per fare in modo che la prima voce nella matrice (Array) contenga le intestazioni di colonna (predefinito = False).

maxrows: definisce il numero massimo di record da restituire. Se il numero di record esistenti è inferiore a maxrows, la grandezza della matrice restituita sarà uguale al numero di record restanti nell'insieme di dati. Lasciare vuoto questo argomento o impostarlo a zero per far restituire tutte le righe dell'insieme di dati (predefinito = 0)

### Esempio:

L'esempio seguente legge un insieme di dati in spezzoni da 100 righe fino a quando l'intero insieme di dati non è stato letto.

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

##### In Python

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

## GetValue

Restituisce il valore del campo specificato nel record corrente dell'insieme di dati.

Se il campo specificato è binario, viene restituita la sua lunghezza.

### Sintassi:

svc.GetValue(fieldname: str): any

### Parametri:

fieldname: il nome del campo da restituire, in formato di stringa che fa distinzione tra lettere minuscole e maiuscole.

### Esempio:

##### In Basic

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

##### In Python

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

## Insert

Inserisce un nuovo record alla fine dell'insieme di dati e inizializza i campi con i valori specificati.

Se la chiave primaria dell'insieme di dati è un valore automatico, questo metodo restituisce la chiave primaria del nuovo record. Altrimenti il metodo restituirà 0 (se eseguito correttamente) o -1 (in caso di errore).

I campi aggiornabili per i quali non è specificato il valore sono inizializzati con i valori predefiniti.

Se il campo specificato è binario, viene restituita la sua lunghezza.

### Sintassi:

svc.Insert(pvargs: any): int

### Parametri:

pvargs: un oggetto di tipo Dictionary contenente delle coppie di nomi dei campi con i rispettivi valori. In alternativa, può essere specificato un numero pari di argomenti alternando i nomi dei campi (in formato String) ai loro valori.

### Esempio:

##### In Basic

Prendendo in considerazione una tabella "Clienti" con 4 campi: "ID" (BigInt, valore automatico e chiave primaria), "Nome" (VarChar), "Età" (Integer), "Città" (VarChar).

L'esempio seguente inserisce un nuovo record in un insieme di dati usando un oggetto di tipo Dictionary.

          oDataset = oDatabase.CreateDataset("Clienti")
          oNewData = CreateScriptService("Dictionary")
          oNewData.Add("Nome", "Giovanni")
          oNewData.Add("Età", 50)
          oNewData.Add("Città", "Roma")
          lNewID = oDataset.Insert(oNewData)

È possibile ottenere lo stesso risultato passando come argomenti tutte le coppie di campi e valori:

          oDataset.Insert("Nome", "Giovanni", "Età", 50, "Città", "Roma")

##### In Python

          dataset = database.CreateDataset("Clienti")
          new_data = {"Nome": "Giovanni", "Età": 30, "Città": "Roma"}
          new_id = dataset.Insert(new_data)

Le seguenti chiamate sono ammesse in Python:

          dataset.Insert("Nome", "Giovanni", "Età", 50, "Città", "Roma")
          dataset.Insert(Nome = "Giovanni", Età = 50, Città = "Roma")

## MoveFirst / MoveLast

Sposta il cursore dell'insieme di dati al primo (con MoveFirst) o all'ultimo (con MoveLast) record.

Questo metodo restituisce True, se eseguito correttamente.

I record eliminati sono ignorati da questo metodo.

### Sintassi:

svc.MoveFirst(): bool

svc.MoveLast(): bool

### Esempio:

##### In Basic

          oDataset.MoveFirst()

##### In Python

          dataset.MoveFirst()

## MoveNext / MovePrevious

Sposta il cursore dell'insieme di dati in avanti (con MoveNext) o indietro (con MovePrevious) di un determinato numero di record.

Questo metodo restituisce True, se eseguito correttamente.

I record eliminati sono ignorati da questo metodo.

### Sintassi:

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

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

### Parametri:

offset: il numero di record di cui il cursore deve essere spostato avanti o indietro. Questo argomento può essere un valore negativo (predefinito = 1).

### Esempio:

##### In Basic

          oDataset.MoveNext()
          oDataset.MoveNext(5)

##### In Python

          dataset.MoveNext()
          dataset.MoveNext(5)

## Reload

Ricarica l'insieme di dati dal database. Le proprietà Filter e OrderBy possono essere definite durante la chiamata a questo metodo.

Questo metodo restituisce True, se eseguito correttamente.

Ricaricare l'insieme di dati è utile quando i record sono stati inseriti o eliminati dal database. Da notare che i metodi CreateDataset e Reload eseguono funzioni simili, però Reload riutilizza la stessa istanza della classe Dataset.

### Sintassi:

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

### Parametri:

filter: specifica la condizione che i record devono rispettare per essere compresi nell'insieme di dati restituito. Questo argomento viene espresso come un'istruzione WHERE di SQL priva della parola chiave "WHERE". Se questo argomento non è specificato, viene applicato il filtro usato nell'insieme di dati corrente, altrimenti il filtro corrente è sostituito da questo argomento.

orderby: specifica l'ordinamento dell'insieme di dati come un'istruzione ORDER BY di SQL priva delle parole chiave "ORDER BY". Se questo argomento non è specificato, viene applicato l'ordinamento corrente dell'insieme di dati, altrimenti l'ordinamento corrente è sostituito da questo argomento.

### Esempio:

##### In Basic

          oDataset.Reload()
          oDataset.Reload(Filter := "[Nome] = 'Giovanni'", OrderBy := "Età")

##### In Python

          dataset.Reload()
          dataset.Reload(Filter = "[Nome] = 'Giovanni'", OrderBy = "Età")

## Update

Aggiorna i valori dei campi specificati del record corrente.

Questo metodo restituisce True, se eseguito correttamente.

### Sintassi:

svc.Update(pvargs: any): bool

### Parametri:

pvargs: un oggetto di tipo Dictionary contenente delle coppie di nomi dei campi con i rispettivi valori. In alternativa, può essere specificato un numero pari di argomenti alternando i nomi dei campi (in formato String) ai loro valori.

### Esempio:

##### In Basic

L'esempio seguente aggiorna il record corrente usando un oggetto di tipo Dictionary.

          oNewValues = CreateScriptService("Dictionary")
          oNewValues.Add("Età", 51)
          oNewValues.Add("Città", "Milano")
          oDataset.Update(oNewValues)

È possibile ottenere lo stesso risultato passando come argomenti tutte le coppie di campi e valori:

          oDataset.Update("Età", 51, "Città", "Milano")

##### In Python

          new_values = {"Età": 51, "Città": "Milano"}
          dataset.Update(new_values)

          dataset.Update("Età", 51, "Città", "Milano")
          dataset.Update(Età = 51, Città = "Milano")

Tutte le routine e gli identificatori Basic di ScriptForge che iniziano con un carattere di sottolineatura "_" sono riservati per uso interno. Non è previsto il loro utilizzo nelle macro in Basic o negli script in Python.

Argomenti correlati

Servizio SFDatabases.Database