Servizio SFDatabases.Database
Il servizio Database fornisce l'accesso sia ai database incorporati, sia a quelli descritti nei documenti di Base. Questo servizio fornisce metodi per:
-
Ottenere l'accesso ai dati nelle tabelle del database.
-
Avviare ricerche con SELECT ed eseguire funzioni aggregate.
-
Eseguire istruzioni SQL come INSERT, UPDATE, DELETE, ecc.
Ogni istanza del servizio Database rappresenta un singolo database e fornisce l'accesso alle sue tabelle, ricerche e dati.
Questo servizio non fornisce accesso ai formulari o ai rapporti del documento di Base che contiene il database. Per accedere ai formulari di un documento di Base, fate riferimento al metodo FormDocuments del servizio Base.
Tutti le transazioni tra questo servizio e il database sono eseguite usando esclusivamente SQL.
Le istruzioni SQL possono essere eseguite in modalità diretta o indiretta. In modalità diretta l'istruzione viene trasferita al motore del database senza alcun controllo della sintassi o revisione.
Le interfacce fornite comprendono semplici elenchi di tabelle e ricerche, così come l'accesso ai dati del database.
Per rendere più leggibili le istruzioni SQL, potete usare le parentesi quadre "[ ]" per racchiudere i nomi di tabelle, ricerche e campi, anziché racchiuderli tra altri caratteri che possono essere di uso esclusivo di determinati RDBMS (Relational Database Management Systems). Prestate comunque attenzione, in questo contesto è obbligatorio usare dei caratteri per racchiudere tali elementi.
Gestione delle transazioni
Per impostazione predefinita il database gestisce le transazioni in modo "deposita" (commit) automatico, il che significa che la trasmissione è effettuata dopo ogni istruzione SQL.
Usare il metodo SetTransactionMode per modificare il comportamento predefinito, che consente di effettuare depositi (commit) manuali e ripristini.
I metodi Commit e Rollback sono usati per delimitare le transazioni.
In LibreOffice, ci sono cinque modi di isolamento delle transazioni, definiti nel gruppo di costanti com.sun.star.sdbc.TransactionIsolation:
|
Costante |
Valore |
Interpretazione |
|---|---|---|
|
NONE |
0 |
La gestione delle transazioni è disabilitata e il database è impostato nel modo predefinito di deposito (commit) automatico. |
|
READ_UNCOMMITTED |
1 |
Possono verificarsi conflitti di lettura, letture non ripetibili o letture fantasma. Se una riga è modificata da una transazione, un'altra transazione sarà in grado di leggere queste modifiche anche se non è stato eseguito il loro deposito (commit). |
|
READ_COMMITTED |
2 |
Previene i conflitti di lettura, possono comunque verificarsi letture non ripetibili e letture fantasma. Questo livello previene la lettura di righe con modifiche per le quali non è stato eseguito il deposito (commit). |
|
REPEATABLE_READ |
4 |
Previene i conflitti di lettura e le letture non ripetibili. Possono comunque verificarsi letture fantasma. Oltre a prevenire la lettura di dati per i quali non è stato eseguito il deposito (commit), previene la possibilità che due operazioni di lettura nella stessa transazione restituiscano risultati differenti. |
|
SERIALIZABLE |
8 |
Previene i conflitti di lettura, le letture non ripetibili e le letture fantasma. In aggiunta ai vincoli del livello precedente, assicura anche che l'insieme dei record corrispondenti a una clausola WHERE rimanga immutato all'interno della stessa transazione. |
Per saperne di più sull'integrità delle transazioni, consultare la pagina Isolation in Database Systems di Wikipedia.
Invocazione del servizio
Prima di usare il servizio Database è necessario caricare o importare le librerie ScriptForge:
• Le macro in Basic richiedono il caricamento della libreria ScriptForge usando la seguente istruzione:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Gli script in Python richiedono un'importazione dal modulo scriptforge:
from scriptforge import CreateScriptService
Per creare un'istanza del servizio Database potete usare il metodo CreateScriptService:
CreateScriptService("SFDatabases.Database", [filename: str], [registrationname], [readonly], [user, [password]]): svc
Nella sintassi sopra descritta potete usare sia "SFDatabases.Database", sia semplicemente "Database" come primo argomento del metodo CreateScriptService.
filename: il nome del file di Base. Deve essere espresso usando la notazione SF_FileSystem.FileNaming.
registrationname: il nome di un database registrato. Se avete indicato un filename, questo argomento non deve essere usato.
Al contrario, se avete specificato registrationname, il parametro filename non deve essere definito.
readonly: determina se il database sarà aperto in sola lettura (predefinito = True).
user, password: parametri aggiuntivi per la connessione al server del database.
GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
Dim myDatabase as Object
Set myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
' Esegue ricerche, istruzioni SQL, ...
myDatabase.CloseDatabase()
from scriptforge import CreateScriptService
myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
# Esegue ricerche, istruzioni SQL, ...
myDatabase.CloseDatabase()
Accedere ai database con il servizio UI
Potete accedere al database associato al documento di Base anche usando il servizio ScriptForge.UI, come mostrato negli esempi sottostanti:
Dim myDoc As Object, myDatabase As Object, ui As Object
Set ui = CreateScriptService("UI")
Set myDoc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
' Utente e password sono fornite di seguito, se necessarie
Set myDatabase = myDoc.GetDatabase()
' Esegue ricerche, istruzioni SQL, ...
myDatabase.CloseDatabase()
myDoc.CloseDocument()
ui = CreateScriptService("UI")
doc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
# Nome utente e password sono fornite di seguito, se necessarie
myDatabase = doc.GetDatabase()
# Esegue ricerche, istruzioni SQL, ...
myDatabase.CloseDatabase()
doc.CloseDocument()
Il metodo GetDatabase usato nell'esempio precedente fa parte del servizio Base di ScriptForge.
Proprietà
|
Nome |
Sola lettura |
Tipo |
Descrizione |
|---|---|---|---|
|
Queries |
Sì |
Matrice di stringhe |
L'elenco delle ricerche memorizzate. |
|
Tables |
Sì |
Matrice di stringhe |
L'elenco delle tabelle memorizzate. |
|
XConnection |
Sì |
L'oggetto UNO che rappresenta la connessione attiva con il database. |
|
|
XMetaData |
Sì |
L'oggetto UNO che rappresenta i metadati che descrivono gli attributi di sistema del database. |
|
Elenco dei metodi del servizio Database |
||
|---|---|---|
CloseDatabase
Chiude la connessione attiva con il database.
db.CloseDatabase()
myDatabase.CloseDatabase() ' Basic
myDatabase.CloseDatabase() # Python
Commit
Effettua il deposito (commit) di tutti gli aggiornamenti fatti dopo l'ultima chiamata di Commit o di Rollback.
Questo metodo viene ignorato se i depositi (commit) sono effettuati automaticamente dopo ogni istruzione SQL, ad esempio quando il database è impostato per usare il modo predefinito di deposito automatico.
db.Commit()
' Imposta il livello di transazione REPEATABLE_READ
myDB.SetTransactionMode(4)
myDB.RunSql("UPDATE ...")
myDB.Commit()
myDB.RunSql("DELETE ...")
' Controlla alcune condizioni prima di effettuare il deposito
If bSomeCondition Then
myDB.Commit()
Else
myDB.Rollback()
End If
' Ripristina il modo di deposito automatico
myDB.SetTransactionMode()
myDB.SetTransactionMode(4)
myDB.RunSql("UPDATE ...")
myDB.Commit()
myDB.RunSql("DELETE ...")
if some_condition:
myDB.Commit()
else:
myDB.Rollback()
myDB.SetTransactionMode()
CreateDataset
Crea un'istanza del servizio Dataset sulla base di una tabella, una ricerca o un'istruzione SELECT di SQL.
db.CreateDataset(sqlcommand: str, opt directsql: bool, opt filter: str, opt orderby: str): svc
sqlcommand: il nome di una tabella, il nome di una ricerca o un'istruzione SELECT valida in SQL. Gli identificatori possono essere racchiusi tra parentesi quadre. Questo argomento fa distinzione tra le minuscole e le maiuscole.
directsql: impostare questo argomento a True per inviare l'istruzione direttamente al motore di database senza che sia prima elaborata da LibreOffice (predefinito = False).
filter: specifica la condizione che i record devono rispettare per essere compresi nell'insieme di dati restituito. Questo argomento è espresso come un'istruzione WHERE in SQL senza la parola chiave "WHERE".
orderby: specifica l'ordinamento dell'insieme di dati come un'istruzione ORDER BY in SQL senza le parole chiave "ORDER BY".
L'esempio seguente in Basic e Python restituisce un insieme di dati con i record di una tabella denominata "Clienti".
oDataset = myDatabase.CreateDataset("Clienti", Filter := "[Name] LIKE 'A'")
dataset = myDatabase.CreateDataset("Clienti", Filter = "[Name] LIKE 'A'")
DAvg, DCount, DMin, DMax, DSum
Calcola la funzione aggregata specificata per un campo o un'espressione appartenente a una tabella.
Facoltativamente è possibile specificare una clausola WHERE di SQL come filtro da applicare prima della funzione aggregata.
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
expression: un'espressione SQL nella quale i nomi dei campi sono racchiusi tra parentesi quadre.
tablename: il nome di una tabella (senza parentesi quadre).
criteria: una clausola WHERE senza la parola chiave "WHERE", nella quale i nomi dei campi sono racchiusi tra parentesi quadre.
L'esempio sottostante presuppone che il file Employees.odb contenga una tabella denominata EmployeeData.
GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
Dim myDB as Variant
Set myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")
'Conta il numero di dipendenti nella tabella
MsgBox myDB.DCount("[ID]", "EmployeeData")
' Restituisce la somma di tutti i salari nella tabella
MsgBox myDB.DSum("[Salary]", "EmployeeData")
'Di seguito trovate alcuni esempi di come si possono filtrare le tabelle
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%'")
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
Calcola un'espressione SQL su di un singolo record restituito dalla clausola WHERE definita nel parametro Criteria.
Se la ricerca restituisce più record, viene considerato solamente il primo. Usate il parametro OrderClause per stabilire come vanno ordinati i risultati della ricerca.
db.DLookup(expression: str, tablename: str, [criteria:str], [orderclause: str]): any
expression: un'espressione SQL nella quale i nomi dei campi sono racchiusi tra parentesi quadre.
tablename: il nome di una tabella (senza parentesi quadre).
criteria: una clausola WHERE senza la parola chiave "WHERE", nella quale i nomi dei campi sono racchiusi tra parentesi quadre.
orderclause: una clausola ORDER BY senza le parole chiave "ORDER BY". I nomi dei campi devono essere racchiusi tra parentesi quadre.
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'")
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
Memorizza in una matrice bidimensionale i contenuti di una tabella o i risultati di una ricerca con SELECT o di un'istruzione SQL. Il primo indice della matrice corrisponde alle righe e il secondo si riferisce alle colonne.
È possibile specificare un limite massimo al numero di righe che vengono restituite. Opzionalmente è possibile inserire i nomi delle colonne nella prima riga della matrice.
La matrice restituita sarà vuota se non viene restituita alcuna riga e le intestazioni di colonna non sono richieste.
db.GetRows(sqlcommand: str, directsql: bool = False, header: bool = False, maxrows: int = 0): any
sqlcommand: il nome di una tabella o di una ricerca (senza parentesi quadre) o un'istruzione SELECT in SQL.
directsql: se impostato su True, il comando SQL viene inviato al motore di database senza una pre-analisi. Il valore predefinito è False. L'argomento viene ignorato per le tabelle. Per le ricerche, l'opzione applicata è quella impostata al momento della creazione della ricerca.
header: se impostato su True, la prima riga della matrice restituita conterrà le intestazioni di colonna.
maxrows: il numero massimo di righe da restituire. Il valore predefinito è zero, ossia un numero illimitato di righe restituite.
Di seguito trovata alcuni esempi di come può essere usato il metodo GetRows:
Dim queryResults as Variant
' Restituisce tutte le righe di una tabella con le intestazioni di colonna
queryResults = myDB.GetRows("EmployeeData", Header := True)
' Restituisce i primi 50 record dei dipendenti ordinati in base al campo 'FirstName'
queryResults = myDB.GetRows("SELECT * FROM EmployeeData ORDER BY [FirstName]", MaxRows := 50)
queryResults = myDB.GetRows("EmployeeData", header = True)
queryResults = myDB.GetRows("SELECT * FROM EmployeeData ORDER BY [FirstName]", maxrows = 50)
OpenFormDocument
Apre il formulario specificato nel modo normale. Questo metodo restituisce un'istanza del servizio FormDocument che corrisponde al formulario specificato.
Se il formulario è già aperto, la sua finestra viene attivata.
Se il formulario specificato non esiste, viene restituito Nothing.
svc.OpenFormDocument(formdocument: str): svc
formdocument: il nome del FormDocument da aprire, espresso come stringa che distingue tra maiuscole e minuscole.
La maggior parte dei formulari è memorizzata nella radice dei documenti di Base e può essere aperta usando semplicemente il loro nome, come nell'esempio seguente:
Dim oFormDoc As Object
oFormDoc = myDB.OpenFormDocument("myFormDocument")
Quando i formulari sono organizzati in cartelle, diventa necessario includere il nome della cartella per specificare il formulario da aprire, come illustrato dall'esempio seguente:
oFormDoc = myDB.OpenFormDocument("myFolder/myFormDocument")
formDoc = myDB.OpenFormDocument("myFormDocument")
formDoc = myDB.OpenFormDocument("myFolder/myFormDocument")
OpenQuery
Apre la finestra Struttura dati della ricerca specificata e restituisce un'istanza del servizio Datasheet.
Se la ricerca non può essere aperta, sarà restituito Nothing.
db.OpenQuery(queryname: str): obj
queryname: il nome di una ricerca esistente in formato stringa con distinzione tra maiuscole e minuscole.
myDatabase.OpenQuery("MyQuery")
myDatabase.OpenQuery("MyQuery")
OpenSql
Esegue un comando SQL SELECT, apre una finestra Struttura dati con i risultati e restituisce un'istanza del servizio Datasheet.
db.OpenSql(sql: str, directsql: bool): obj
sql: una stringa contenente un'istruzione SELECT valida in SQL. Gli identificatori possono essere racchiusi in parentesi quadre.
directsql: se impostato su True, il comando SQL è inviato al motore del database senza pre-analisi (predefinito = False).
myDatabase.OpenSql("SELECT * FROM [Customers] ORDER BY [CITY]")
myDatabase.OpenSql("SELECT * FROM [Customers] ORDER BY [CITY]")
OpenTable
Apre la finestra Struttura dati della tabella specificata e restituisce un'istanza del servizio Datasheet.
db.OpenTable(tablename: str): obj
tablename: il nome di una tabella esistente in formato stringa con distinzione tra maiuscole e minuscole.
myDatabase.OpenTable("MyTable")
myDatabase.OpenTable("MyTable")
Rollback
Elimina tutte le modifiche apportate al database dopo l'ultima chiamata di Commit o Rollback.
db.Rollback()
myDB.SetTransactionMode(1)
myDB.RunSql("UPDATE ...")
' ...
If bSomeCondition Then
myDB.Rollback()
End If
myDB.SetTransactionMode(1)
myDB.RunSql("UPDATE ...")
# ...
if bSomeCondition:
myDB.Rollback()
RunSql
Esegue una ricerca attiva di un'istruzione SQL come la creazione di una tabella, oppure l'inserimento, la modifica e l'eliminazione di record.
Il metodo restituisce True, se eseguito correttamente.
Il metodo RunSql viene respinto con un messaggio di errore nel caso in cui il database in precedenza era stato aperto in modalità di sola lettura.
db.RunSql(sqlcommand: str, directsql: bool = False): bool
sqlcommand: il nome di una ricerca (senza parentesi quadre) o un'istruzione SQL.
directsql: se impostato su True, il comando SQL viene inviato al motore del database senza una pre-analisi (predefinito = False). Per le ricerche, l'opzione applicata è quella impostata al momento della definizione della ricerca.
myDatabase.RunSql("INSERT INTO [EmployeeData] VALUES(25, 'Smith', 'John')", DirectSQL := True)
myDatabase.RunSql("INSERT INTO [EmployeeData] VALUES(25, 'Smith', 'John')", directsql = True)
SetTransactionMode
Definisce il livello di isolamento delle transazioni del database.
Per impostazione predefinita i database gestiscono le transazione nel modo di deposito (commit) automatico, che significa che viene eseguito automaticamente un Commit dopo ogni istruzione SQL.
Usare questo metodo per determinare manualmente il livello di isolamento delle transazioni. Quando per le transazioni è impostato un modo diverso da NONE, lo script deve chiamare esplicitamente il metodo Commit affinché le modifiche siano applicate al database.
Questo metodo restituisce True, se eseguito correttamente.
La modifica del modo delle transazioni chiude tutte le istanze di Dataset create dal database corrente.
db.SetTransactionMode(transactionmode: int = 0): bool
transactionmode: Specifica il modo per le transazioni. Questo argomento deve esser una delle costanti definite in com.sun.star.sdbc.TransactionIsolation (predefinito = NONE)
Per saperne di più sul livello di isolamento delle transazioni usato in LibreOffice, leggere la precedente sezione Gestione delle transazioni.
myDB.SetTransactionMode(com.sun.star.sdbc.TransactionIsolation.REPEATABLE_READ)
oDataset = myDB.CreateDataset("SELECT ...")
' ...
' Reimposta il modo predefinito per le transazioni
myDB.SetTransactionMode()
from com.sun.star.sdbc import TransactionIsolation
myDB.SetTransactionMode(TransactionIsolation.REPEATABLE_READ)
dataset = myDB.CreateDataset("SELECT ...")
# ...
myDB.SetTransactionMode()
Tutte le routine e gli identificatori Basic di ScriptForge che iniziano con un carattere di sottolineatura "_" sono riservati per uso interno. Non è previsto il loro utilizzo nelle macro in Basic o negli script in Python.