Service SFDatabases.Dataset

Contenu

# ServiceSFDatabases.Dataset

Le service Dataset est utilisé pour représenter des données tabulaires produites par une base de données. Avec ce service, il est possible de :

- Naviguer et accéder aux données dans un ensemble de données.

- Mettre à jour, insérer et supprimer des enregistrements dans un ensemble de données.

La mise à jour et l'insertion d'enregistrements à l'aide du service Dataset sont plus lentes qu'à l'aide d'instructions SQL. Lors de la mise à jour ou de l'insertion d'un grand nombre d'enregistrements, il est recommandé d'utiliser des instructions SQL au lieu d'utiliser les méthodes de ce service.

## Invocation du service

Avant d'utiliser le service Dataset, la bibliothèque ScriptForge doit être chargée ou importée :

• Les macros Basic nécessitent de charger la bibliothèque ScriptForge à l'aide de l'instruction suivante :
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Les scripts Python nécessitent un import depuis le module scriptforge :
from scriptforge import CreateScriptService

Le service Dataset est invoqué à l'aide de la méthode CreateDataset, qui peut être appelée soit à partir d'une instance de service Database, soit à partir d'un autre instance Dataset

##### En Basic :

L'exemple suivant crée un Dataset à partir de la table "Customers" stockée dans un fichier de base de données.

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

Lors de la création du Dataset, l'enregistrement courant est positionné avant le premier enregistrement.

L'exemple ci-dessous crée une instance Dataset en filtrant l'ensemble de données d'origine.

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

##### En Python

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

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

## Propriétés

Nom | En lecture seule | Type | Description
--- | --- | --- | ---
BOF | Non | Boolean | Renvoie True si la position actuelle de l'enregistrement est avant le premier enregistrement de l'ensemble de données, sinon renvoie False. Définissez cette propriété sur True pour déplacer le curseur au début de l'ensemble de données. La définition de cette propriété sur False est ignorée.
DefaultValues | Oui | Service Dictionary | Renvoie un Dictionary avec les valeurs par défaut utilisées pour chaque champ de l'ensemble de données. Les champs ou colonnes de l'ensemble de données sont les clés du dictionnaire. Les types de champs de base de données sont convertis en leurs types de données Basic/Python correspondants. Lorsque le type de champ n'est pas défini, la valeur par défaut est Null si le champ peut être nul ou Vide.
EOF | No | Boolean | Renvoie True si la position actuelle de l'enregistrement est après le dernier enregistrement de l'ensemble de données, sinon renvoie False. Définissez cette propriété sur True pour déplacer le curseur à la fin de l'ensemble de données. La définition de cette propriété sur False est ignorée.
Fields | Oui | Array | Renvoie une Array contenant les noms de tous les champs de l'ensemble de données
Filter | Oui | String | Renvoie le filtre appliqué en plus des éventuelles clauses WHERE dans l'instruction SQL initiale. Cette propriété est exprimée sous la forme d'une clause WHERE sans le mot clé "WHERE".
OrderBy | Oui | String | Renvoie la clause de tri qui remplace l'éventuelle clause ORDER BY présente dans l'instruction SQL initiale. Cette propriété est exprimée sous la forme d'une clause ORDER BY sans les mots-clés "ORDER BY".
ParentDatabase | Oui | Service Database | Renvoie l'instance Database correspondant à la base de données parent de l'ensemble de données actuel.
RowCount | Oui | Long | Renvoie le nombre exact d'enregistrements dans l'ensemble de données. Notez que l'évaluation de cette propriété implique de parcourir l'ensemble des données, ce qui peut être coûteux en fonction de la taille de l'ensemble de données.
RowNumber | Oui | Long | Renvoie le numéro de l'enregistrement actuel commençant à 1. Renvoie 0 si cette propriété est inconnue.
Source | Oui | String | Renvoie la source de l'ensemble de données. Il peut s'agir d'un nom de table, d'un nom de requête ou d'une instruction SQL.
SourceType | Oui | String | Renvoie la source de l'ensemble de données. Il peut s'agir de l'une des valeurs de chaîne suivantes : TABLE, QUERY ou SQL.
UpdatableFields | Oui | Array | Renvoie une Array contenant les noms des champs de l'ensemble de données pouvant être mis à jour.
Values | Oui | Array | Renvoie un Dictionary contenant les paires (nom du champ : valeur) de l'enregistrement actuel dans l'ensemble de données.
XRowSet | Oui | Objet UNO | Renvoie l'objet UNO com.sun.star.sdb.RowSet représentant l'ensemble de données.

Liste des méthodes dans le service Dataset
CloseDataset CreateDataset Delete ExportValueToFile GetRows | GetValue Insert MoveFirst MoveLast | MoveNext MovePrevious Reload Update

## CloseDataset

Ferme l'ensemble de données actuel. Cette méthode renvoie True en cas de succès.

Il est recommandé de fermer le jeu de données après son utilisation pour libérer des ressources.

### Syntaxe :

svc.CloseDataset(): bool

### Exemple :

##### En Basic :

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

##### En Python

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

## CreateDataset

Renvoie une instance de service Dataset à partir d'un ensemble de données existant en appliquant le filtre spécifié et les instructions ORDER BY .

### Syntaxe :

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

### Paramètres :

filter : spécifie la condition à laquelle les enregistrements doivent correspondre pour être inclus dans l'ensemble de données renvoyé. Cet argument est exprimé sous la forme d'une instruction SQL WHERE sans le mot clé "WHERE". Si cet argument n'est pas spécifié, alors le filtre utilisé dans le jeu de données actuel est appliqué, sinon le filtre actuel est remplacé par cet argument.

orderby : spécifie l'ordre de l'ensemble de données sous la forme d'une instruction SQL ORDER BY sans le mot clé "ORDER BY". Si cet argument n'est pas spécifié, alors l'ordre de tri utilisé dans l'ensemble de données actuel est appliqué, sinon l'ordre de tri actuel est remplacé par cet argument.

### Exemple :

##### En Basic :

          ' Utiliser une chaîne vide pour supprimer le filtre actuel
          oNewDataset = oDataset.CreateDataset(Filter := "")
          ' Exemples de filtres usuels
          oNewDataset = oDataset.CreateDataset(Filter := "[Name] = 'John'")
          oNewDataset = oDataset.CreateDataset(Filter := "[Name] LIKE 'A'")
          ' Il est possible d'ajouter des conditions supplémentaires au filtre actuel
          oNewDataset = oDataset.CreateDataset(Filter := "(" & oDataset.Filter & ") AND [Name] LIKE 'A'")

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

Supprime l'enregistrement actuel de l'ensemble de données. Cette méthode renvoie True en cas de succès.

Après cette opération, le curseur est positionné sur l'enregistrement immédiatement après l'enregistrement supprimé. Si l'enregistrement supprimé est le dernier de l'ensemble de données, alors le curseur est positionné après lui et la propriété EOF renvoie True.

### Syntaxe :

svc.Delete(): bool

### Exemple :

##### En Basic :

          oDataset.Delete()

##### En Python

          dataset.Delete()

## ExportValueToFile

Exporte la valeur d'un champ binaire de l'enregistrement courant vers le fichier spécifié.

Si le champ spécifié n'est pas binaire ou s'il ne contient aucune donnée, alors le fichier de sortie n'est pas créé.

### Syntaxe :

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

### Paramètres :

fieldname : le nom du champ binaire à exporter, sous forme de chaîne sensible à la casse.

filename : le chemin complet du fichier à créer en utilisant la notation définie dans la propriété FileSystem.FileNaming.

overwrite : définissez cet argument sur True pour permettre l'écrasement du fichier de destination (par défaut = False).

### Exemple :

Dans l'exemple ci-dessous, l'ensemble de données contient un champ nommé "Picture" qui doit être exporté vers un fichier image.

##### En Basic :

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

##### En Python

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

## GetRows

Renvoie le contenu de l'ensemble de données dans une matrice à 2 dimensions, en commençant par le premier enregistrement après l'enregistrement actuel.

Après l'exécution, le curseur est positionné sur la ligne qui a été lue pour la dernière fois ou après le dernier enregistrement de l'ensemble de données, auquel cas la propriété EOF renvoie True.

Cette méthode peut être utilisée pour lire les données de l'ensemble de données en morceaux, dont la taille est définie par l'argument maxrows.

La matrice renvoyée aura toujours deux dimensions, même si l'ensemble de données contient une seule colonne et un seul enregistrement.

### Syntaxe :

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

### Paramètres :

header : définissez cet argument sur True pour que la première entrée de Array contienne les en-têtes de colonnes (par défaut = False).

maxrows : définit le nombre maximum d'enregistrements à renvoyer. Si le nombre d'enregistrements existants est inférieur à maxrows, alors la taille de la matrice renvoyée sera égale au nombre d'enregistrements restants dans l'ensemble de données. Laissez cet argument vide ou définissez-le sur zéro pour renvoyer toutes les lignes de l'ensemble de données (par défaut = 0)

### Exemple :

L'exemple suivant lit un ensemble de données par morceaux de 100 lignes jusqu'à ce que tout l'ensemble de données ait été lu.

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

##### En Python

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

## GetValue

Renvoie la valeur du champ spécifié à partir de l'enregistrement actuel de l'ensemble de données.

Si le champ spécifié est binaire, sa longueur est renvoyée.

### Syntaxe :

svc.GetValue(fieldname: str): any

### Paramètres :

fieldname : le nom du champ à renvoyer, sous forme de chaîne sensible à la casse.

### Exemple :

##### En Basic :

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

##### En Python

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

## Insert

Insère un nouvel enregistrement à la fin de l'ensemble de données et initialise ses champs avec les valeurs spécifiées.

Si la clé primaire de l'ensemble de données est une valeur automatique, cette méthode renvoie la valeur de clé primaire du nouvel enregistrement. Sinon, la méthode renverra 0 (en cas de succès) ou -1 (en cas d'échec).

Les champs pouvant être mis à jour avec des valeurs non spécifiées sont initialisés avec leurs valeurs par défaut.

Si le champ spécifié est binaire, sa longueur est renvoyée.

### Syntaxe :

svc.Insert(pvargs: any): int

### Paramètres :

pvargs : un Dictionary contenant des paires de noms de champs et leurs valeurs respectives. Alternativement, un nombre pair d'arguments peut être spécifié en alternant les noms de champs (sous forme de String) et leurs valeurs.

### Exemple :

##### En Basic :

Considérons une table nommée "Customers" avec 4 champs : "ID" (BigInt, valeur automatique et clé primaire), "Name" (VarChar), "Age" (Integer), "City" (VarChar).

L'exemple ci-dessous insère un nouvel enregistrement dans cet ensemble de données à l'aide de Dictionary.

          oDataset = oDatabase.CreateDataset("Customers")
          oNewData = CreateScriptService("Dictionary")
          oNewData.Add("Name", "John")
          oNewData.Add("Age", 50)
          oNewData.Add("City", "Chicago")
          lNewID = oDataset.Insert(oNewData)

Le même résultat peut être obtenu en passant toutes les paires de champs et de valeurs comme arguments :

          oDataset.Insert("Name", "John", "Age", 50, "City", "Chicago")

##### En Python

          dataset = database.CreateDataset("Customers")
          new_data = {"Name": "John", "Age": 30, "City": "Chicago"}
          new_id = dataset.Insert(new_data)

Les appels suivants sont acceptés en Python :

          dataset.Insert("Name", "John", "Age", 50, "City", "Chicago")
          dataset.Insert(Name = "John", Age = 50, City = "Chicago")

## MoveFirst / MoveLast

Déplace le curseur de l'ensemble de données vers le premier (avec MoveFirst) ou vers le dernier (avec MoveLast) enregistrement.

Cette méthode renvoie True en cas de succès.

Les enregistrements supprimés sont ignorés par cette méthode.

### Syntaxe :

svc.MoveFirst(): bool

svc.MoveLast(): bool

### Exemple :

##### En Basic :

          oDataset.MoveFirst()

##### En Python

          dataset.MoveFirst()

## MoveNext / MovePrevious

Déplace le curseur de l'ensemble de données vers l'avant (avec MoveNext) ou vers l'arrière (avec MovePrevious) d'un nombre donné d'enregistrements.

Cette méthode renvoie True en cas de succès.

Les enregistrements supprimés sont ignorés par cette méthode.

### Syntaxe :

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

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

### Paramètres :

offset : nombre d'enregistrements dont le curseur doit être déplacé vers l'avant ou vers l'arrière. Cet argument peut être une valeur négative (par défaut = 1).

### Exemple :

##### En Basic :

          oDataset.MoveNext()
          oDataset.MoveNext(5)

##### En Python

          dataset.MoveNext()
          dataset.MoveNext(5)

## Reload

Recharge l'ensemble de données à partir de la base de données. Les propriétés Filter et OrderBy peuvent être définies lors de l'appel de cette méthode.

Cette méthode renvoie True en cas de succès.

Le rechargement de l'ensemble de données est utile lorsque des enregistrements ont été insérés ou supprimés de la base de données. Notez que les méthodes CreateDataset et Reload exécutent des fonctions similaires, cependant Reload réutilise la même instance de classe Dataset.

### Syntaxe :

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

### Paramètres :

filter : spécifie la condition à laquelle les enregistrements doivent correspondre pour être inclus dans l'ensemble de données renvoyé. Cet argument est exprimé sous la forme d'une instruction SQL WHERE sans le mot clé "WHERE". Si cet argument n'est pas spécifié, alors le filtre utilisé dans le jeu de données actuel est appliqué, sinon le filtre actuel est remplacé par cet argument.

orderby : spécifie l'ordre de l'ensemble de données sous la forme d'une instruction SQL ORDER BY sans le mot clé "ORDER BY". Si cet argument n'est pas spécifié, alors l'ordre de tri utilisé dans l'ensemble de données actuel est appliqué, sinon l'ordre de tri actuel est remplacé par cet argument.

### Exemple :

##### En Basic :

          oDataset.Reload()
          oDataset.Reload(Filter := "[Name] = 'John'", OrderBy := "Age")

##### En Python

          dataset.Reload()
          dataset.Reload(Filter = "[Name] = 'John'", OrderBy = "Age")

## Update

Mettre à jour les valeurs des champs spécifiés dans l'enregistrement actuel.

Cette méthode renvoie True en cas de succès.

### Syntaxe :

svc.Update(pvargs: any): bool

### Paramètres :

pvargs : un Dictionary contenant des paires de noms de champs et leurs valeurs respectives. Alternativement, un nombre pair d'arguments peut être spécifié en alternant les noms de champs (sous forme de String) et leurs valeurs.

### Exemple :

##### En Basic :

L'exemple ci-dessous met à jour l'enregistrement actuel à l'aide d'un Dictionary.

          oNewValues = CreateScriptService("Dictionary")
          oNewValues.Add("Age", 51)
          oNewValues.Add("City", "New York")
          oDataset.Update(oNewValues)

Le même résultat peut être obtenu en passant toutes les paires de champs et de valeurs comme arguments :

          oDataset.Update("Age", 51, "City", "New York")

##### En Python

          new_values = {"Age": 51, "City": "New York"}
          dataset.Update(new_values)

          dataset.Update("Age", 51, "City", "New York")
          dataset.Update(Age = 51, City = "New York")

Toutes les routines ou identifiants de base ScriptForge qui sont préfixés par un caractère de soulignement "_" sont réservés à un usage interne. Ils ne sont pas destinés à être utilisés dans des macros de base ou des scripts Python.

Rubriques connexes

SFDatabases.Database