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.


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 LibreOffice, 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.


tip

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 :

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

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.

note

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 LibreOffice (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.

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)
    

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.

warning

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)

note

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


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