Услуга SFDatabases.Database

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

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

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

note

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


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

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

tip

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


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

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

note

• Макросите на Basic изискват зареждане на библиотеката ScriptForge чрез следния оператор:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Скриптовете на Python изискват импортиране от модула scriptforge:
from scriptforge import CreateScriptService


Синтаксис:

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

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

note

В описания по-горе синтаксис можете да използвате или "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()
    
tip

Методът 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

Изпълнява заявка за действие или оператор на SQL от рода на създаване на таблица или вмъкване, промяна или изтриване на записи.

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

tip

Методът 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)
    
warning

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


D'oh! You found a bug (text/sbasic/shared/03/sf_datasheet.xhp#DatasheetService not found).