Съдържание
Индекс 🔎︎

# Услуга SFDatabases.Database

Услугата Database предоставя достъп до вградени или описани в документи на Base бази от данни. Тази услуга предлага методи за:

- получаване на достъп до таблици в база от данни

- стартиране на заявки SELECT и изчисляване на агрегатни функции

- изпълнение на оператори за действия на SQL като INSERT, UPDATE, DELETE и т.н.

Всеки екземпляр на услугата Database представя единична база от данни и дава достъп до нейните таблици, заявки и данни.

Тази услуга не предлага достъп до формуляри или справки в документа на Base, който съдържа базата от данни. За достъп до формуляри в документи на Base вижте метода FormDocuments на услугата Base.

Целият обмен между тази услуга и базата от данни се извършва само посредством SQL.

Оператори на SQL може да се изпълняват в пряк или непряк режим. В пряк режим операторът се предава към СУБД без проверка на синтаксиса или преглеждане.

Предлаганите интерфейси включват прости списъци на таблиците и заявките, както и достъп до данните в базата от данни.

За да направите операторите на SQL по-четливи, може да ограждате имената на таблици, заявки и полета с квадратни скоби „[ ]“, вместо с други ограждащи знаци, които може да се поддържат само от определени системи за управление на бази от данни (СУБД). Но имайте предвид, че в този контекст ограждащите знаци са задължителни.

## Извикване на услугата

Преди да използвате услугата Database, библиотеката ScriptForge трябва да бъде заредена или импортирана:

• Макросите на Basic изискват зареждане на библиотеката ScriptForge чрез следния оператор:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Скриптовете на Python изискват импортиране от модула scriptforge:
from scriptforge import CreateScriptService

### Синтаксис:

За да създадете екземпляр на услугата Database, може да използвате метода CreateScriptService:

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

В описания по-горе синтаксис можете да използвате или "SFDatabases.Database", или просто "Database" като първи аргумент на метода CreateScriptService.

### Параметри:

filename: името на файла на Base. То трябва да следва нотацията, зададена с SF_FileSystem.FileNaming.

registrationname: името на регистрирана база от данни. Ако е подаден filename, този аргумент не трябва да се използва.

Обратно, ако е зададен registrationname, параметърът filename не трябва да е дефиниран.

readonly: определя дали базата от данни да се отвори само за четене (подразбира се True).

user, password: допълнителни параметри на връзката към сървъра на базата от данни.

### Пример:

##### В Basic

          GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
          Dim myDatabase as Object
          Set myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
          ' Изпълняване на заявки, оператори на SQL, ...
          myDatabase.CloseDatabase()

##### В Python

          from scriptforge import CreateScriptService
          myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
          # Изпълняване на заявки, оператори на SQL, ...
          myDatabase.CloseDatabase()

## Достъп до бази от данни с услугата UI

Достъпът до базата от данни, свързана с документ на Base, е възможен и чрез услугата ScriptForge.UI, както е показано в следващите примери:

##### В Basic

          Dim myDoc As Object, myDatabase As Object, ui As Object
          Set ui = CreateScriptService("UI")
          Set myDoc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
          ' Потребителят (user) и паролата (password) се подават по-долу, ако е необходимо.
          Set myDatabase = myDoc.GetDatabase()
          ' Изпълняване на заявки, оператори на SQL, ...
          myDatabase.CloseDatabase()
          myDoc.CloseDocument()

##### В Python

          ui = CreateScriptService("UI")
          doc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
          # Потребителят (user) и паролата (password) се подават по-долу, ако е необходимо.
          myDatabase = doc.GetDatabase()
          # Изпълняване на заявки, оператори на SQL, ...
          myDatabase.CloseDatabase()
          doc.CloseDocument()

Методът GetDatabase, използван в горния пример, е част от услугата Base на ScriptForge.

## Свойства

Име | Само за четене | Тип | Описание
--- | --- | --- | ---
Queries | Да | Масив от низове | Списъкът от съхранени заявки.
Tables | Да | Масив от низове | Списъкът от съхранени таблици.
XConnection | Да | XConnection | UNO обектът, представящ текущата връзка с база от данни.
XMetaData | Да | XDatabaseMetaData | UNO обектът, представящ метаданните, които описват системните атрибути на базата от данни.

Списък с методи на услугата Database
CloseDatabase DAvg DCount DMin | DMax DSum DLookup GetRows | OpenQuery OpenSql OpenTable RunSql

## CloseDatabase

Затваря текущата връзка с база от данни.

### Синтаксис:

db.CloseDatabase()

### Пример:

        myDatabase.CloseDatabase() ' Basic

        myDatabase.CloseDatabase() # Python

## DAvg, DCount, DMin, DMax, DSum

Изчислява дадената агрегатна функция върху поле или израз от таблица.

По желание може да се зададе клауза на SQL WHERE като филтър, който да бъде приложен преди агрегатната функция.

### Синтаксис:

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: израз на SQL, в който имената на полета са оградени с квадратни скоби.

tablename: име на таблица (без квадратни скоби).

criteria: клауза WHERE без ключовата дума WHERE, в която имената на полета са оградени с квадратни скоби.

### Пример:

В долния пример се приема, че файлът Employees.odb съдържа таблица с име EmployeeData.

##### В Basic

          GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
          Dim myDB as Variant
          Set myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")
          ' Преброява служителите в таблицата.
          MsgBox myDB.DCount("[ID]", "EmployeeData")
          ' Връща сумата на всички заплати в таблицата.
          MsgBox myDB.DSum("[Salary]", "EmployeeData")
          ' Следват няколко примера за филтриране на таблици.
          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%'")

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

Изчислява израз на SQL върху единичен запис, върнат от клауза WHERE, която е дефинирана в параметъра Criteria.

Ако заявката върне няколко записа, се взема само първият от тях. Използвайте параметъра OrderClause, за да определите как се сортират резултатите от заявката.

### Синтаксис:

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

### Параметри:

expression: израз на SQL, в който имената на полета са оградени с квадратни скоби.

tablename: име на таблица (без квадратни скоби).

criteria: клауза WHERE без ключовата дума WHERE, в която имената на полета са оградени с квадратни скоби.

orderclause: клауза ORDER BY без ключовите думи ORDER BY. Имената на полета трябва да бъдат оградени с квадратни скоби.

### Пример:

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

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

Съхранява съдържанието на таблица или резултатите от заявка SELECT или оператор на SQL в двуизмерен масив. Първият индекс на масива съответства на редовете, а вторият представя колоните.

Може да бъде зададена горна граница за броя върнати записи. По желание имената на колоните могат да бъдат вмъкнати в първия ред на масива.

Резултатният масив ще бъде празен, ако не са върнати редове и не се изискват заглавия на колони.

### Синтаксис:

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

### Параметри:

sqlcommand: име на таблица или заявка (без квадратни скоби) или оператор SELECT на SQL.

directsql: когато е True, командата на SQL се изпраща към СУБД без предварителен анализ. Подразбира се False. Аргументът се игнорира за таблици. За заявки прилаганата настройка е тази, която е била зададена при създаване на заявката.

header: когато е True, първият ред на върнатия масив съдържа заглавията на колоните.

maxrows: максималният брой върнати редове. Подразбира се нула, което означава, че няма ограничение за броя връщани редове.

### Пример:

Следват няколко примера за употребата на метода GetRows:

##### В Basic

          Dim queryResults as Variant
          ' Връща всички редове в таблицата и заглавията на колоните.
          queryResults = myDB.GetRows("EmployeeData", Header := True)
          ' Връща първите 50 записа за служители, подредени по полето FirstName.
          queryResults = myDB.GetRows("SELECT * FROM EmployeeData ORDER BY [FirstName]", MaxRows := 50)

##### В Python

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

## OpenQuery

Отваря прозореца „Изглед с данни“ на указаната заявка и връща екземпляр на услугата Datasheet.

Ако заявката не може да бъде отворена, се връща Nothing.

### Синтаксис:

db.OpenQuery(queryname: str): obj

### Параметри:

queryname: името на съществуваща заявка като низ, малките и главните букви се различават.

### Пример:

##### В Basic

          myDatabase.OpenQuery("MyQuery")

##### В Python

          myDatabase.OpenQuery("MyQuery")

## OpenSql

Изпълнява команда SELECT на SQL, отваря прозорец „Изглед с данни“ с резултатите и връща екземпляр на услугата Datasheet.

### Синтаксис:

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

### Параметри:

sql: низ, съдържащ валиден оператор SELECT на SQL. Идентификаторите може да бъдат оградени с квадратни скоби.

directsql: когато е True, командата на SQL се изпраща към системата за управление на бази от данни без предварителен анализ (подразбира се False).

### Пример:

##### В Basic

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

##### В Python

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

## OpenTable

Отваря прозореца „Изглед с данни“ на указаната таблица и връща екземпляр на услугата Datasheet.

### Синтаксис:

db.OpenTable(tablename: str): obj

### Параметри:

tablename: името на съществуваща таблица като низ, малките и главните букви се различават.

### Пример:

##### В Basic

          myDatabase.OpenTable("MyTable")

##### В Python

          myDatabase.OpenTable("MyTable")

## RunSql

Executes an action query of an SQL statement such as creating a table, as well as inserting, updating and deleting records.

Методът връща True при успех.

Методът RunSql се отказва със съобщение за грешка, ако базата от данни е била отворена в режим само за четене.

### Синтаксис:

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

### Параметри:

sqlcommand: име на заявка (без квадратни скоби) или оператор на SQL.

directsql: когато е True, командата на SQL се изпраща към СУБД без предварителен анализ. Подразбира се False. За заявки прилаганата настройка е тази, която е била зададена при създаване на заявката.

### Пример:

##### В Basic

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

##### В Python

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

В ScriptForge всички подпрограми или идентификатори на Basic с префикс „_“ са запазени за вътрешна употреба. Те не са предназначени за използване в макроси на Basic.

Теми, свързани с показаната

SFDatabases.Datasheet service

SFDocuments.Document service

SFDocuments.Form service

ScriptForge.UI service