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:

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:

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.

Servizio SFDatabases.Database