Guida di LibreOffice 25.2
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.
Prima di usare il servizio Dataset è necessario caricare o importare le librerie ScriptForge:
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.
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'")
  
    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'")
  | 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 dizionario (Dictionary) con i valori predefiniti per ogni campo del dataset. I campi o le colonne del dataset sono le chiavi nel 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 | ||
|---|---|---|
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.
svc.CloseDataset(): bool
      oDataset = oDatabase.CreateDataset("MyTable")
      ' ...
      oDataset.CloseDataset()
    
      dataset = database.CreateDataset("MyTable")
      # ...
      dataset.CloseDataset()
    Restituisce un'istanza del servizio Dataset da un dataset già esistente applicando il filtro e l'istruzione ORDER BY specificati.
svc.CreateDataset(opt filter: str, opt orderby: str): svc
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.
      ' Usa una stringa vuota per eliminare il filtro corrente
      oNewDataset = oDataset.CreateDataset(Filter := "")
      ' Esempi di filtri comuni
      oNewDataset = oDataset.CreateDataset(Filter := "[Nome] = 'John'")
      oNewDataset = oDataset.CreateDataset(Filter := "[Nome] LIKE 'A'")
      ' È possibile applicare condizioni aggiuntive al filtro corrente
      oNewDataset = oDataset.CreateDataset(Filter := "(" & oDataset.Filter & ") AND [Nome] LIKE 'A'")
    
      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'")
    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.
svc.Delete(): bool
      oDataset.Delete()
    
      dataset.Delete()
    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.
svc.ExportValueToFile(fieldname: str, filename: str, overwrite: bool): bool
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).
Nell'esempio sottostante l'insieme di dati contiene un campo denominato "Picture" che deve essere esportato in un file immagine.
      oDataset.ExportValueToFile("Picture", "C:\mia_immagine.png", True)
    
      dataset.ExportValueToFile("Picture", r"C:\mia_immagine.png", True)
    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.
svc.GetRows(header: bool, maxrows: int): any
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)
L'esempio seguente legge un insieme di dati in spezzoni da 100 righe fino a quando l'intero insieme di dati non è stato letto.
      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
    
      max_rows = 100
      chunk = dataset.GetRows(maxrows = max_rows)
      while len(chunk) > 0:
          # ...
          chunk = dataset.GetRows(maxrows = max_rows)
    Restituisce il valore del campo specificato nel record corrente dell'insieme di dati.
Se il campo specificato è binario, viene restituita la sua lunghezza.
svc.GetValue(fieldname: str): any
fieldname: il nome del campo da restituire, in formato di stringa che fa distinzione tra lettere minuscole e maiuscole.
      currId = oDataset.GetValue(FieldName := "ID")
    
      curr_id = dataset.GetValue(fieldname = "ID")
    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.
svc.Insert(pvargs: any): int
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.
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")
    
      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")
    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.
svc.MoveFirst(): bool
svc.MoveLast(): bool
      oDataset.MoveFirst()
    
      dataset.MoveFirst()
    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.
svc.MoveNext(offset: int = 1): bool
svc.MovePrevious(offset: int = 1): bool
offset: il numero di record di cui il cursore deve essere spostato avanti o indietro. Questo argomento può essere un valore negativo (predefinito = 1).
      oDataset.MoveNext()
      oDataset.MoveNext(5)
    
      dataset.MoveNext()
      dataset.MoveNext(5)
    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.
svc.Reload(opt filter: str, opt orderby: str): bool
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.
      oDataset.Reload()
      oDataset.Reload(Filter := "[Nome] = 'Giovanni'", OrderBy := "Età")
    
      dataset.Reload()
      dataset.Reload(Filter = "[Nome] = 'Giovanni'", OrderBy = "Età")
    Aggiorna i valori dei campi specificati del record corrente.
Questo metodo restituisce True, se eseguito correttamente.
svc.Update(pvargs: any): bool
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.
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")
    
      new_values = {"Età": 51, "Città": "Milano"}
      dataset.Update(new_values)
    
      dataset.Update("Età", 51, "Città", "Milano")
      dataset.Update(Età = 51, Città = "Milano")