Contenu
Index 🔎︎

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

- Accéder aux données des tables de la base de données.

- Exécuter des requêtes SELECT et exécuter des fonctions d'agrégation.

- Exécuter des instructions d'action SQL telles que INSERT, UPDATE, DELETE, etc.

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.

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.

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.

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

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.

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)

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.

Rubriques connexes

SFDocuments.Document service

ScriptForge.UI service