Service SFDatabases.Database

Le service Database permet d'accéder aux bases de données intégrées ou décrites dans les documents Base. Ce service fournit des méthodes pour :

Chaque instance du service Database représente une seule base de données et donne accès à ses tables, requêtes et données.

Ce service ne donne pas accès aux formulaires ou aux rapports du document Base qui contient la base de données. Pour accéder aux formulaires dans un document Base, reportez-vous à la méthode FormDocuments du service Base.

note

Tous les échanges entre ce service et la base de données se font uniquement en SQL.


Les instructions SQL peuvent être exécutées en mode direct ou indirect. En mode direct, l'instruction est transférée au moteur de base de données sans aucune vérification ou révision de la syntaxe.

Les interfaces fournies incluent des tables et des listes de requêtes simples, ainsi qu'un accès aux données de la base de données.

tip

Pour rendre les instructions SQL plus lisibles, vous pouvez utiliser des crochets "[ ]" afin d'inclure les noms de tables, de requêtes et de champs au lieu d'utiliser d'autres caractères englobants qui peuvent être exclusifs à certains systèmes de gestion de bases de données relationnelles (SGBDR). Mais attention, les caractères englobants sont obligatoires dans ce contexte.


Invocation du service

Before using the Database service the ScriptForge library needs to be loaded or imported:

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


Syntaxe :

Pour créer une instance du service Database, vous pouvez utiliser la méthode CreateScriptService :

CreateScriptService("SFDatabases.Database", [filename: str], [registrationname], [readonly], [user, [password]]): svc

note

Dans la syntaxe décrite ci-dessus, vous pouvez utiliser "SFDatabases.Database" ou simplement "Database" comme premier argument de la méthode CreateScriptService.


Paramètres :

filename : le nom du fichier Base. Il doit être exprimé en utilisant la notation SF_FileSystem.FileNaming.

registrationname : le nom d'une base de données enregistrée. Si filename est fourni, cet argument ne doit pas être utilisé.

Inversement, si un registrationname est spécifié, le paramètre filename ne doit pas être défini.

readonly : détermine si la base de données sera ouverte en lecture seule (par défaut = True).

user, password : paramètres de connexion supplémentaires au serveur de base de données.

Exemple :

En Basic :

      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDatabase as Object
      Set myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      '  requêtes Run, instructions SQL, ...
      myDatabase.CloseDatabase()
    
En Python

      from scriptforge import CreateScriptService
      myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      #  requêtes Run, instructions SQL, ...
      myDatabase.CloseDatabase()
    

Accéder aux bases de données à l'aide du service UI

Il est également possible d'accéder à la base de données associée à un document Base à l'aide du service ScriptForge.UI, comme illustré dans les exemples ci-dessous :

En Basic :

      Dim myDoc As Object, myDatabase As Object, ui As Object
      Set ui = CreateScriptService("UI")
      Set myDoc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      ' L'utilisateur et le mot de passe sont fournis ci-dessous, si nécessaire
      Set myDatabase = myDoc.GetDatabase()
      '  requêtes Run, instructions SQL, ...
      myDatabase.CloseDatabase()
      myDoc.CloseDocument()
    
En Python

      ui = CreateScriptService("UI")
      doc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      # L'utilisateur et le mot de passe sont fournis ci-dessous, si nécessaire
      myDatabase = doc.GetDatabase()
      #  requêtes Run, instructions SQL, ...
      myDatabase.CloseDatabase()
      doc.CloseDocument()
    
tip

The GetDatabase method used in the example above is part of ScriptForge's Base service.


Propriétés

Nom

Lecture seule

Type

Description

Queries

Oui

Matrice de chaînes

La liste des requêtes stockées.

Tables

Oui

Matrice de chaînes

La liste des tables stockées.

XConnection

Oui

XConnection

L'objet UNO représentant la connexion à la base de données active.

XMetaData

Oui

XDatabaseMetaData

L'objet UNO représentant les métadonnées décrivant les attributs du système de base de données.


Liste des méthodes dans le service Database

CloseDatabase
DAvg
DCount
DMin

DMax
DSum
DLookup
GetRows

OpenQuery
OpenSql
OpenTable
RunSql


CloseDatabase

Ferme la connexion à la base de données active.

Syntaxe :

db.CloseDatabase()

Exemple :


    myDatabase.CloseDatabase() ' Basic
  

    myDatabase.CloseDatabase() # Python
  

DAvg, DCount, DMin, DMax, DSum

Calcule la fonction d'agrégat donnée sur un champ ou une expression appartenant à une table.

Facultativement, une clause SQL WHERE peut être spécifiée comme filtre qui sera appliqué avant la fonction d'agrégation.

Syntaxe :

db.DAvg(expression: str, tablename: str, [criteria: str]): any

db.DCount(expression: str, tablename: str, [criteria: str]): any

db.DMin(expression: str, tablename: str, [criteria: str]): any

db.DMax(expression: str, tablename: str, [criteria: str]): any

db.DSum(expression: str, tablename: str, [criteria: str]): any

Paramètres :

expression : une expression SQL dans laquelle les noms de champ sont entourés de crochets.

tablename : un nom de table (sans crochets).

criteria : une clause WHERE sans le mot-clé "WHERE", dans laquelle les noms de champs sont entourés de crochets.

Exemple :

L'exemple ci-dessous suppose que le fichier Employees.odb a une table nommée EmployeeData.

En Basic :

      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDB as Variant
      Set myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")
      ' Compte le nombre d'employés dans la table
      MsgBox myDB.DCount("[ID]", "EmployeeData")
      ' Renvoie la somme de tous les salaires dans la table
      MsgBox myDB.DSum("[Salary]", "EmployeeData")
      ' Vous trouverez ci-dessous quelques exemples de filtrage des tableaux
      MsgBox myDB.DCount("[ID]", "EmployeeData", "[Position] = 'Manager'")
      MsgBox myDB.DCount("[ID]", "EmployeeData", "[Position] = 'Sales' AND [City] = 'Chicago'")
      MsgBox myDB.DCount("[ID]", "EmployeeData", "[FirstName] LIKE 'Paul%'")
    
En Python

      myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")
      bas = CreateScriptService("Basic")
      bas.MsgBox(myDB.DCount("[ID]", "EmployeeData"))
      bas.MsgBox(myDB.DSum("[Salary]", "EmployeeData"))
      bas.MsgBox(myDB.DCount("[ID]", "EmployeeData", "[Position] = 'Manager'"))
      bas.MsgBox(myDB.DCount("[ID]", "EmployeeData", "[Position] = 'Sales' AND [City] = 'Chicago'"))
      bas.MsgBox(myDB.DCount("[ID]", "EmployeeData", "[FirstName] LIKE 'Paul%'"))
    

DLookup

Calcule une expression SQL sur un seul enregistrement renvoyé par une clause WHERE définie par le paramètre Criteria.

Si la requête renvoie plusieurs enregistrements, seul le premier est pris en compte. Utilisez le paramètre OrderClause pour déterminer comment les résultats de la requête sont triés.

Syntaxe :

db.DLookup(expression: str, tablename: str, [criteria:str], [orderclause: str]): any

Paramètres :

expression : une expression SQL dans laquelle les noms de champ sont entourés de crochets.

tablename : un nom de table (sans crochets).

criteria : une clause WHERE sans le mot-clé "WHERE", dans laquelle les noms de champs sont entourés de crochets.

orderclause : une clause ORDER BY sans les mots clés "ORDER BY". Les noms de champs doivent être entourés de crochets.

Exemple :

En Basic :

      MsgBox myDB.DLookup("[FirstName]", "EmployeeData", Criteria := "[LastName] LIKE 'Smith'", OrderClause := "[FirstName] DESC")
      MsgBox myDB.DLookup("[Salary]", "EmployeeData", Criteria := "[ID] = '3'")
      MsgBox myDB.DLookup("[Quantity] * [Value]", "Sales", Criteria := "[SaleID] = '5014'")
    
En Python

      bas = CreateScriptService("Basic")
      bas.MsgBox(myDB.DLookup("[FirstName]", "EmployeeData", criteria = "[LastName] LIKE 'Smith'", orderclause = "[FirstName] DESC"))
      bas.MsgBox(myDB.DLookup("[Salary]", "EmployeeData", criteria = "[ID] = '3'"))
      bas.MsgBox(myDB.DLookup("[Quantity] * [Value]", "Sales", criteria = "[SaleID] = '5014'"))
    

GetRows

Stocke le contenu d'une table ou les résultats d'une requête SELECT ou d'une instruction SQL dans une matrice à deux dimensions. Le premier index de la matrice correspond aux lignes et le second index fait référence aux colonnes.

Une limite supérieure peut être spécifiée pour le nombre de lignes renvoyées. En option, les noms de colonne peuvent être insérés dans la première ligne de la matrice.

La matrice renvoyée sera vide si aucune ligne n'est renvoyée et que les entêtes de colonne ne sont pas requis.

Syntaxe :

db.GetRows(sqlcommand: str, directsql: bool = False, header: bool = False, maxrows: int = 0): any

Paramètres :

sqlcommand : un nom de table ou de requête (sans crochets) ou une instruction SQL SELECT.

directsql : lorsque True, la commande SQL est envoyée au moteur de base de données sans pré-analyse. La valeur par défaut est False. Cet argument est ignoré pour les tables. Pour les requêtes, l'option appliquée est celle définie lors de la définition de la requête.

header : lorsque True, la première ligne de la matrice renvoyée contient les en-têtes de colonne.

maxrows : le nombre maximum de lignes à renvoyer. La valeur par défaut est zéro, ce qui signifie qu'il n'y a pas de limite au nombre de lignes renvoyées.

Exemple :

Voici quelques exemples d'utilisation de la méthode GetRows :

En Basic :

      Dim queryResults as Variant
      ' Renvoie toutes les lignes du tableau avec les en-têtes de colonne
      queryResults = myDB.GetRows("EmployeeData", Header := True)
      ' Renvoie les 50 premiers enregistrements d'employés triés par le champ 'FirstName'
      queryResults = myDB.GetRows("SELECT * FROM EmployeeData ORDER BY [FirstName]", MaxRows := 50)
    
En Python

      queryResults = myDB.GetRows("EmployeeData", header = True)
      queryResults = myDB.GetRows("SELECT * FROM EmployeeData ORDER BY [FirstName]", maxrows = 50)
    

OpenQuery

Opens the Data View window of the specified query and returns an instance of the Datasheet service.

If the query could not be opened, then Nothing is returned.

Syntaxe :

db.OpenQuery(queryname: str): obj

Paramètres :

queryname: The name of an existing query as a case-sensitive String.

Exemple :

En Basic :

      myDatabase.OpenQuery("MyQuery")
    
En Python

      myDatabase.OpenQuery("MyQuery")
    

OpenSql

Runs a SQL SELECT command, opens a Data View window with the results and returns an instance of the Datasheet service.

Syntaxe :

db.OpenSql(sql: str, directsql: bool): obj

Paramètres :

sql: A string containing a valid SQL SELECT statement. Identifiers may be enclosed by square brackets.

directsql: When True, the SQL command is sent to the database engine without pre-analysis (Default = False).

Exemple :

En Basic :

      myDatabase.OpenSql("SELECT * FROM [Customers] ORDER BY [CITY]")
    
En Python

      myDatabase.OpenSql("SELECT * FROM [Customers] ORDER BY [CITY]")
    

OpenTable

Opens the Data View window of the specified table and returns an instance of the Datasheet service.

Syntaxe :

db.OpenTable(tablename: str): obj

Paramètres :

tablename: The name of an existing table as a case-sensitive String.

Exemple :

En Basic :

      myDatabase.OpenTable("MyTable")
    
En Python

      myDatabase.OpenTable("MyTable")
    

RunSql

Executes an action query or an SQL statement such as creating a table, as well as inserting, updating and deleting records.

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

tip

La méthode RunSql est rejetée avec un message d'erreur dans le cas où la base de données a été précédemment ouverte en mode lecture seule.


Syntaxe :

db.RunSql(sqlcommand: str, directsql: bool = False): bool

Paramètres :

sqlcommand : un nom de requête (sans crochets) ou une instruction SQL.

directsql : lorsque True, la commande SQL est envoyée au moteur de base de données sans pré-analyse (par défaut = False). Pour les requêtes, l'option appliquée est celle définie lors de la définition de la requête.

Exemple :

En Basic :

      myDatabase.RunSql("INSERT INTO [EmployeeData] VALUES(25, 'Smith', 'John')", DirectSQL := True)
    
En Python

      myDatabase.RunSql("INSERT INTO [EmployeeData] VALUES(25, 'Smith', 'John')", directsql = True)
    
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.


D'oh! You found a bug (text/sbasic/shared/03/sf_datasheet.xhp#DatasheetService not found).