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 :

warning

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 :

note

• 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
  
note

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

Returns a Dictionary with the default values used for each field in the dataset. The fields or columns in the dataset are the keys in the dictionary.

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.

note

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

Returns a Dataset service instance from an existing dataset by applying the specified filter and ORDER BY statements.

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 :

      ' 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'")
    
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é.

note

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.

note

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.

note

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).

note

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


note

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.

note

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.

note

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.

tip

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")
    
warning

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.


Aidez-nous !