Contenuto
Indice 🔎︎

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

## Invocare il 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

### Sintassi:

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.

### Parametri:

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.

### Esempio:

##### In Basic

          GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
          Dim myDatabase as Object
          Set myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
          ' Esegue ricerche, istruzioni SQL, ...
          myDatabase.CloseDatabase()

##### In Python

          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:

##### In Basic

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

##### In Python

          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ì | XConnection | L'oggetto UNO che rappresenta la connessione attiva con il database.
XMetaData | Sì | XDatabaseMetaData | L'oggetto UNO che rappresenta i metadati che descrivono gli attributi di sistema del database.

Elenco dei metodi del servizio Database
CloseDatabase DAvg DCount | DMin DMax DSum | DLookup GetRows RunSql

## CloseDatabase

Chiude la connessione attiva con il database.

### Sintassi:

db.CloseDatabase()

### Esempio:

        myDatabase.CloseDatabase() ' Basic

        myDatabase.CloseDatabase() # Python

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

### Sintassi:

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

### Parametri:

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.

### Esempio:

L'esempio sottostante presuppone che il file Employees.odb contenga una tabella denominata EmployeeData.

##### In Basic

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

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

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.

### Sintassi:

db.DLookup(expression: str, tablename: str, [criteria:str], [orderclause: str]): any

### Parametri:

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.

### Esempio:

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

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

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.

### Sintassi:

db.GetRows(sqlcommand: str, directsql: bool = False, header: bool = False, maxrows: int = 0): any

### Parametri:

sqlcommand: il nome di una tabella o di una ricerca (senza parentesi quadre) o un'istruzione SELECT in SQL.

directsql: se 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 è 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.

### Esempio:

Di seguito trovata alcuni esempi di come può essere usato il metodo GetRows:

##### In Basic

          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)

##### In Python

          queryResults = myDB.GetRows("EmployeeData", header = True)
          queryResults = myDB.GetRows("SELECT * FROM EmployeeData ORDER BY [FirstName]", maxrows = 50)

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

### Sintassi:

db.RunSql(sqlcommand: str, directsql: bool = False): bool

### Parametri:

sqlcommand: il nome di una ricerca (senza parentesi quadre) o un'istruzione SQL.

directsql: se è 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.

### Esempio:

##### In Basic

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

##### In Python

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

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.

Argomenti correlati

Servizio SFDocuments.Document

Servizio SFDocuments.Form

Servizio ScriptForge.UI