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.

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.

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.

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.

Traitement des transactions

Par défaut, la base de données gère les transactions en mode de validation automatique, ce qui signifie qu'une validation est effectuée après chaque instruction SQL.

Utilisez la méthode SetTransactionMode pour modifier le comportement par défaut, qui permet des validations et des restaurations manuelles.

Les méthodes Commit et Rollback sont utilisées pour délimiter les transactions.

Dans Collabora Office, il existe cinq types de modes d'isolation des transactions, tels que définis dans le groupe de constantes com.sun.star.sdbc.TransactionIsolation :

Constante	Valeur	Interprétation
NONE	0	La gestion des transactions est désactivée et la base de données est définie sur le mode de validation automatique par défaut.
READ_UNCOMMITTED	1	Des lectures sales, des lectures non répétables et des lectures fantômes peuvent se produire. Si une ligne est modifiée par une transaction, une autre transaction pourra lire ces modifications même si elles n'ont pas été validées.
READ_COMMITTED	2	Les lectures sales sont évitées, mais des lectures non répétables et des lectures fantômes peuvent se produire. Ce niveau empêche la lecture des lignes contenant des modifications non validées.
REPEATABLE_READ	4	Les lectures sales et les lectures non répétables sont évitées. Toutefois, des lectures fantômes peuvent se produire. En plus d'empêcher la lecture des données non validées, cela empêche également que deux opérations de lecture dans la même transaction renvoient des résultats différents.
SERIALIZABLE	8	Les lectures sales, les lectures non répétables et les lectures fantômes sont évitées. En plus des contraintes du niveau précédent, cela garantit également que l'ensemble des enregistrements qui correspondent à une clause WHERE reste inchangé au sein de la même transaction.

Lisez la page Wikipédia sur Isolation dans les systèmes de bases de données pour en savoir plus sur l'intégrité des transactions.

Invocation du service

Avant d'utiliser le service Database, 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

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

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

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

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 Commit CreateDataset DAvg DCount DMin	DMax DSum DLookup GetRows OpenFormDocument OpenQuery	OpenSql OpenTable Rollback RunSql SetTransactionMode

CloseDatabase

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

Syntaxe :

db.CloseDatabase()

Exemple :

myDatabase.CloseDatabase() ' Basic

myDatabase.CloseDatabase() # Python

Commit

Valide toutes les mises à jour effectuées depuis le précédent appel Commit ou Rollback.

Cette méthode est ignorée si les validations sont effectuées automatiquement après chaque instruction SQL, c'est-à-dire que la base de données est définie sur le mode de validation automatique par défaut.

Syntaxe :

db.Commit()

Exemple :

En Basic :

' Définissez le niveau de transaction REPEATABLE_READ
myDB.SetTransactionMode(4)
myDB.RunSql("UPDATE ...")
myDB.Commit()
myDB.RunSql("DELETE ...")
' Testez certaines conditions avant de valider
If bSomeCondition Then
    myDB.Commit()
Else
    myDB.Rollback()
End If
' Restaurer le mode de validation automatique
myDB.SetTransactionMode()

En Python

myDB.SetTransactionMode(4)
myDB.RunSql("UPDATE ...")
myDB.Commit()
myDB.RunSql("DELETE ...")
if some_condition:
    myDB.Commit()
else:
    myDB.Rollback()
myDB.SetTransactionMode()

CreateDataset

Crée une instance de service Dataset basée sur une table, une requête ou une instruction SQL SELECT.

Syntaxe :

db.CreateDataset(sqlcommand: str, opt directsql: bool, opt filter: str, opt orderby: str): svc

Paramètres :

sqlcommand : un nom de table, un nom de requête ou une instruction SQL SELECT valide. Les identifiants peuvent être placés entre crochets. Cet argument est sensible à la casse.

directsql : définissez cet argument sur True pour envoyer l'instruction directement au moteur de base de données sans prétraitement par Collabora Office (par défaut = False).

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

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

Exemple :

Les exemples suivants en Basic et Python renvoient un ensemble de données avec les enregistrements d'une table nommée "Customers".

En Basic :

oDataset = myDatabase.CreateDataset("Customers", Filter := "[Name] LIKE 'A'")

En Python

dataset = myDatabase.CreateDataset("Customers", Filter = "[Name] LIKE 'A'")

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)

OpenFormDocument

Ouvre le document de formulaire spécifié en mode normal. Cette méthode renvoie une instance de service FormDocument correspondant au document de formulaire spécifié.

Si le document de formulaire est déjà ouvert, la fenêtre du document de formulaire est activée.

Si le document de formulaire spécifié n'existe pas, alors Rien est renvoyé.

Syntaxe :

svc.OpenFormDocument(formdocument: str): svc

Paramètres :

formdocument : Le nom du FormDocument à ouvrir, sous forme de chaîne sensible à la casse.

Exemple :

En Basic :

La plupart des documents de formulaire sont stockés à la racine du document Base et peuvent être ouverts simplement en utilisant leur nom, comme dans l'exemple ci-dessous :

Dim oFormDoc As Object
oFormDoc = myDB.OpenFormDocument("myFormDocument")

Si les documents de formulaire sont organisés en dossiers, il devient nécessaire d'inclure le nom du dossier pour spécifier le document de formulaire à ouvrir, comme illustré dans l'exemple suivant :

oFormDoc = myDB.OpenFormDocument("myFolder/myFormDocument")

En Python

formDoc = myDB.OpenFormDocument("myFormDocument")

formDoc = myDB.OpenFormDocument("myFolder/myFormDocument")

OpenQuery

Ouvre la fenêtre Affichage des données de la requête spécifiée et renvoie une instance du service Datasheet.

Si la requête n'a pas pu être ouverte, alors Nothing est renvoyé.

Syntaxe :

db.OpenQuery(queryname: str): obj

Paramètres :

queryname : le nom d'une requête existante sous forme de chaîne sensible à la casse.

Exemple :

En Basic :

myDatabase.OpenQuery("MyQuery")

En Python

myDatabase.OpenQuery("MyQuery")

OpenSql

Exécute une commande SQL SELECT, ouvre une fenêtre d'affichage des données avec les résultats et renvoie une instance du service Datasheet.

Syntaxe :

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

Paramètres :

sql : une chaîne contenant une instruction SQL SELECT valide. Les identificateurs peuvent être entourés de crochets.

directsql : lorsque True, la commande SQL est envoyée au moteur de base de données sans pré-analyse (par défaut = False).

Exemple :

En Basic :

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

En Python

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

OpenTable

Ouvre la fenêtre Affichage des données de la table spécifiée et renvoie une instance du service Datasheet.

Syntaxe :

db.OpenTable(tablename: str): obj

Paramètres :

tablename : le nom d'une table existante sous la forme d'une chaîne sensible à la casse.

Exemple :

En Basic :

myDatabase.OpenTable("MyTable")

En Python

myDatabase.OpenTable("MyTable")

Rollback

Annule toutes les modifications apportées à la base de données depuis le dernier appel Commit ou Rollback.

Syntaxe :

db.Rollback()

Exemple :

En Basic :

myDB.SetTransactionMode(1)
myDB.RunSql("UPDATE ...")
' ...
If bSomeCondition Then
    myDB.Rollback()
End If

En Python

myDB.SetTransactionMode(1)
myDB.RunSql("UPDATE ...")
# ...
if bSomeCondition:
    myDB.Rollback()

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 :

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)

SetTransactionMode

Définit le niveau d'isolement dans les transactions de base de données.

Par défaut, les bases de données gèrent les transactions en mode de validation automatique, ce qui signifie qu'un Commit est automatiquement effectué après chaque instruction SQL.

Utilisez cette méthode pour déterminer manuellement le niveau d’isolement des transactions. Lorsqu'un mode de transaction autre que NONE est défini, le script doit appeler explicitement la méthode Commit pour appliquer les modifications à la base de données.

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

La modification du mode de transaction ferme toutes les instances Dataset créées à partir de la base de données actuelle.

Syntaxe :

db.SetTransactionMode(transactionmode: int = 0): bool

Paramètres :

transactionmode : spécifie le mode de transaction. Cet argument doit être l'une des constantes définies dans com.sun.star.sdbc.TransactionIsolation (par défaut = NONE)

Lisez la section Gestion des transactions ci-dessus pour en savoir plus sur les niveaux d'isolement des transactions utilisés dans Collabora Office.

Exemple :

En Basic :

myDB.SetTransactionMode(com.sun.star.sdbc.TransactionIsolation.REPEATABLE_READ)
oDataset = myDB.CreateDataset("SELECT ...")
' ...
' Réinitialiser le mode de transaction par défaut
myDB.SetTransactionMode()

En Python

from com.sun.star.sdbc import TransactionIsolation
myDB.SetTransactionMode(TransactionIsolation.REPEATABLE_READ)
dataset = myDB.CreateDataset("SELECT ...")
# ...
myDB.SetTransactionMode()

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.

Service SFDatabases.Datasheet

ServiceSFDatabases.Dataset

Service SFDocuments.Document

SFDocuments. Service Form

Service ScriptForge.UI