SFDatabases.Database service

Inhoud
Index 🔎︎

# SFDatabases.Database-service

De service Database biedt toegang tot databases die zijn ingesloten of beschreven in Base-documenten. Deze service biedt methoden om:

- Krijg toegang tot gegevens in databasetabellen.

- SELECT query's en aggregatiefuncties uitvoeren.

- SQL-instructies, zoals INSERT, UPDATE, DELETE, enz uitvoeren.

Elk exemplaar van de Database-service vertegenwoordigt een enkele database en geeft toegang tot de tabellen, query's en gegevens.

Deze service biedt geen toegang tot formulieren of rapporten in het basisdocument dat de database bevat. Om toegang te krijgen tot formulieren in een basisdocument, raadpleegt u de methode FormDocuments van de Base-service.

Alle uitwisselingen tussen deze service en de database gebeuren alleen met SQL.

SQL-instructies kunnen worden uitgevoerd in de modus direct of indirect. In de directe modus wordt de instructie overgebracht naar de database-engine zonder enige syntaxiscontrole of herziening.

De geboden interfaces omvatten eenvoudige tabellen en querylijsten, evenals toegang tot databasegegevens.

Om SQL-instructies leesbaarder te maken, kunt u vierkante haken "[ ]" gebruiken om namen van tabellen, query's en velden te omsluiten in plaats van andere omsluitende tekens te gebruiken die exclusief kunnen zijn voor bepaalde relationele databasebeheersystemen (RDBMS). Maar pas op dat het insluiten van tekens in deze context verplicht is.

## Service aanroep

Voordat de service Database gebruikt kan worden, moet de bibliotheek ScriptForge eerst worden geladen of geïmporteerd:

• Basic macro's kunnen de bibliotheek ScriptForge laden met de instructie:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python scripts kunnen de module scriptforge importeren met:
from scriptforge import CreateScriptService

### Syntaxis:

Om een instantie van de Database-service te maken, kunt u de CreateScriptService-methode gebruiken:

CreateScriptService("SFDatabases.Database", [filename: str], [registrationname], [readonly], [user, [password]]): svc

In de hierboven beschreven syntaxis kunt u ofwel "SFDatabases.Database" of gewoon "Database" gebruiken als het eerste argument van de CreateScriptService-methode.

### Parameters:

filename: De naam van het basisbestand. Moet worden uitgedrukt met de notatie SF_FileSystem.FileNaming.

registrationname: De naam van een geregistreerde database. Als filename is opgegeven, mag dit argument niet worden gebruikt.

Omgekeerd, als een registrationname is opgegeven, moet de parameter filename niet worden gedefinieerd.

readonly: Bepaalt of de database wordt geopend als alleen-lezen (Standaard = True).

user, password: Aanvullende verbindingsparameters voor de databaseserver.

### Voorbeeld:

##### In BASIC

          GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
          Dim myDatabase as Object
          Set myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
          ' Query's, SQL statements, ... uitvoeren
          myDatabase.CloseDatabase()

##### In Python

          from scriptforge import CreateScriptService
          myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
          # Query's, SQL statements, ... uitvoeren
          myDatabase.CloseDatabase()

## Toegang tot databases met de UI-service

Het is ook mogelijk om toegang te krijgen tot de database die is gekoppeld aan een basisdocument met behulp van de ScriptForge.UI-service, zoals weergegeven in de onderstaande voorbeelden:

##### 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")
          ' Gebruiker en wachtwoord worden hieronder vermeld, indien nodig
          Set myDatabase = myDoc.GetDatabase()
          ' Query's, SQL statements, ... uitvoeren
          myDatabase.CloseDatabase()
          myDoc.CloseDocument()

##### In Python

          ui = CreateScriptService("UI")
          doc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
          # Gebruikersnaam en wachtwoord worden hieronder vermeld, indien nodig
          myDatabase = doc.GetDatabase()
          # Query's, SQL statements, ... uitvoeren
          myDatabase.CloseDatabase()
          doc.CloseDocument()

De methode GetDatabase die in het bovenstaande voorbeeld wordt gebruikt, maakt deel uit van ScriptForge's Base onderhoud.

## Eigenschappen

Naam | AlleenLezen | Type | Beschrijving
--- | --- | --- | ---
Queries | Ja | Matrix met tekenreeksen | De lijst met opgeslagen query's.
Tables | Ja | Matrix met tekenreeksen | De lijst met opgeslagen query's.
XConnection | Ja | XConnection | Het UNO-object dat de huidige databaseverbinding vertegenwoordigt.
XMetaData | Ja | XDatabaseMetaData | Het UNO-object dat de metagegevens vertegenwoordigt die de kenmerken van het databasesysteem beschrijven.

Lijst met methoden in de databaseservice
CloseDatabase DAvg DCount | DMin DMax DSum | DLookup GetRows RunSql

## CloseDatabase

Sluit de huidige databaseverbinding.

### Syntaxis:

db.CloseDatabase()

### Voorbeeld:

        myDatabase.CloseDatabase() ' Basic

        myDatabase.CloseDatabase() # Python

## DAvg, DCount, DMin, DMax, DSum

Berekent de gegeven aggregatiefunctie voor een veld of expressie die bij een tabel hoort.

Optioneel kan een SQL WHERE-clausule worden opgegeven als een filter dat wordt toegepast voorafgaand aan de aggregatiefunctie.

### Syntaxis:

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

### Parameters:

expression: Een SQL-expressie waarin de veldnamen tussen vierkante haken staan.

tablename: Een tabelnaam (zonder vierkante haken).

criteria: Een WHERE-clausule zonder het trefwoord "WHERE", waarin veldnamen tussen vierkante haken staan.

### Voorbeeld:

In het onderstaande voorbeeld wordt ervan uitgegaan dat het bestand Employees.odb een tabel heeft met de naam EmployeeData.

##### In BASIC

          GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
          Dim myDB as Variant
          Set myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")
          ' Telt het aantal medewerkers in de tabel
          MsgBox myDB.DCount("[ID]", "EmployeeData")
          ' Retourneert de som van alle salarissen in de tabel
          MsgBox myDB.DSum("[Salary]", "EmployeeData")
          ' Hieronder staan enkele voorbeelden van hoe tabellen kunnen worden gefilterd
          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

Berekent een SQL-expressie op een enkele record die wordt geretourneerd door een WHERE-clausule gedefinieerd door de parameter Criteria.

Als de query meerdere records retourneert, wordt alleen de eerste in aanmerking genomen. Gebruik de parameter OrderClause om te bepalen hoe zoekopdrachtresultaten worden gesorteerd.

### Syntaxis:

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

### Parameters:

expression: Een SQL-expressie waarin de veldnamen tussen vierkante haken staan.

tablename: Een tabelnaam (zonder vierkante haken).

criteria: Een WHERE-clausule zonder het trefwoord "WHERE", waarin veldnamen tussen vierkante haken staan.

orderclause: Een ORDER BY-clausule zonder de trefwoorden "ORDER BY". Veldnamen moeten tussen vierkante haken staan.

### Voorbeeld:

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

Slaat de inhoud van een tabel of de resultaten van een SELECT-query of van een SQL-instructie op in een tweedimensionale matrix. De eerste index in de matrix komt overeen met de rijen en de tweede index verwijst naar de kolommen.

Er kan een bovengrens worden opgegeven voor het aantal geretourneerde rijen. Optioneel kunnen kolomnamen worden ingevoegd in de eerste rij van de matrix.

De geretourneerde matrix is leeg als er geen rijen worden geretourneerd en de kolomkoppen niet vereist zijn.

### Syntaxis:

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

### Parameters:

sqlcommand: Een tabel- of querynaam (zonder vierkante haken) of een SELECT SQL-instructie.

directsql: Wanneer True, wordt de SQL-opdracht zonder voorafgaande analyse naar de database-engine gestuurd. Standaard is False. Dit argument wordt genegeerd voor tabellen. Voor query's is de toegepaste optie de optie die is ingesteld toen de query werd gedefinieerd.

header: Indien True, bevat de eerste rij van de geretourneerde matrix de kolomkoppen.

maxrows: Het maximum aantal rijen dat moet worden geretourneerd. De standaardwaarde is nul, wat betekent dat er geen limiet is aan het aantal geretourneerde rijen.

### Voorbeeld:

Hieronder staan een paar voorbeelden van hoe de methode GetRows kan worden gebruikt:

##### In BASIC

          Dim queryResults as Variant
          ' Retourneert alle rijen in de tabel met kolomkoppen
          queryResults = myDB.GetRows("EmployeeData", Header := True)
          ' Retourneert de eerste 50 werknemersrecords gerangschikt op het veld 'Voornaam'
          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

Voert een actiequery uit van een SQL-instructie, zoals het maken van een tabel, evenals het invoegen, bijwerken en verwijderen van records.

De methode retourneert True wanneer succesvol.

De methode RunSql wordt afgewezen met een foutmelding als de database eerder in alleen-lezen modus is geopend.

### Syntaxis:

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

### Parameters:

sqlcommand: Een querynaam (zonder vierkante haken) of een SQL-instructie.

directsql: Wanneer True, wordt de SQL-opdracht zonder voorafgaande analyse naar de database-engine gestuurd. (Standaard = False). Voor query's is de toegepaste optie de optie die is ingesteld toen de query werd gedefinieerd.

### Voorbeeld:

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

Alle ScriptForge Basic-routines of variabelen die beginnen met een underscore "_" zijn voor intern gebruik. Gebruik deze niet in een Basic of Python-macro.

Verwante onderwerpen

SFDocuments.Document-service

SFDocuments.Form-service

Service ScriptForge.UI