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 :

Each instance of the Database service represents a single database and gives access to its tables, queries and data. This service does not provide access to forms or reports in the Base document.

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

To make SQL statements more readable, you can use optional square brackets to enclose tables, queries and fields instead of using other enclosing characters that may be exclusive to certain Relational Database Management Systems (RDBMS).


Invocation du service

Syntaxe :

The code snippet below shows how to access any database with the Database service.


        Dim myDatabase As Object
        Set myDatabase = CreateScriptService("SFDatabases.Database", [FileName], [RegistrationName], [ReadOnly], [User, [Password]])
        '   ... Run queries, SQL statements, ...
        myDatabase.CloseDatabase()
    

Paramètres :

FileName: The name of the Base file. Must be expressed using SF_FileSystem.FileNaming notation.

RegistrationName: The name of a registered database. If a file name is provided, this argument should not be used.

Conversely, if a RegistrationName is specified, the FileName parameter should not be defined.

ReadOnly: Determines if the database will be opened as readonly (Default = True).

User, Password: Additional connection parameters to the database server.

note

Ce service est complètement pris en charge par les langages Basic et Python. Tous les exemples sont exprimés en utilisant le langage de programmation Basic et peuvent facilement être convertis en Python.


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

It is also possible to access the database associated with a Base document using the ScriptForge.UI service, as shown in the example below:


        Dim myDoc As Object, myDatabase As Object, ui As Object
        Set ui = CreateScriptService("UI")
        Set myDoc = ui.OpenBaseDocument("myDb.odb")
        ' L'utilisateur et le mot de passe sont fournis ci-dessous, si nécessaire
        Set myDatabase = myDoc.GetDatabase()
        '   ... Run queries, SQL statements, ...
        myDoc.CloseDocument()
    
tip

La méthode GetDatabase utilisée dans l'exemple ci-dessus fait partie du service ScriptForge Base.


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
RunSql


CloseDatabase

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

Syntaxe :


       myDatabase.CloseDatabase()
     

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 :


        myDatabase.DAvg(Expression As String, TableName As String, [Criteria As String]) As Variant
    

Paramètres :

Expression: A SQL expression in which the field names are surrounded with square brackets.

TableName: A table name (without square brackets).

Criteria: A WHERE clause without the "WHERE" keyword, in which field names are surrounded with square brackets.

Exemple :

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


      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDB as Variant
      Set myDB = CreateScriptService("Database", "~/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%'")
    

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 :


        myDatabase.DLookup(Expression As String, TableName As String, [Criteria As String], [OrderClause As String]) As Variant
    

Paramètres :

Expression: A SQL expression in which the field names are surrounded with square brackets.

TableName: A table name (without square brackets).

Criteria: A WHERE clause without the "WHERE" keyword, in which field names are surrounded with square brackets.

OrderClause: An ORDER BY clause without the "ORDER BY" keywords. Field names should be surrounded with square brackets.

Exemple :


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

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 :


        myDatabase.GetRows(SQLCommand As String, [DirectSQL As Boolean], [Header As Boolean], [MaxRows As Long]) As Variant
    

Paramètres :

SQLCommand: A table or query name (without square brackets) or a SELECT SQL statement.

DirectSQL: When True, the SQL command is sent to the database engine without pre-analysis. Default is False. This argument is ignored for tables. For queries, the applied option is the one set when the query was defined.

Header: When True, the first row of the returned array contains the column headers.

MaxRows: The maximum number of rows to return. The default is zero, meaning there is no limit to the number of returned rows.

Exemple :

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


        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)
    

RunSql

Exécute une requête d'action d'une instruction SQL telle que la création d'une table, ainsi que l'insertion, la mise à jour et la suppression d'enregistrements.

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 :


        myDatabase.RunSql(SQLCommand As String, [DirectSQL As Boolean]) As Boolean
    

Paramètres :

SQLCommand: A query name (without square brackets) or a SQL statement.

DirectSQL: When True, the SQL command is sent to the database engine without pre-analysis. (Default = False). For queries, the applied option is the one set when the query was defined.

Exemple :


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

Toutes les routines ou identificateurs Basic ScriptForge précédés d'un trait de soulignement "_" sont réservés à un usage interne. Ils ne sont pas destinés à être utilisés dans les macros Basic.