Услуга SFDatabases.Dataset

Услугата Dataset служи за представяне на таблични данни, предоставени от база от данни. Тази услуга позволява:

навигация в набор от данни и достъп до данните в него;
променяне, вмъкване и премахване на записи в набор от данни.

Променянето и вмъкването на записи чрез услугата Dataset е по-бавно, отколкото чрез оператори на SQL. Когато променяте или вмъквате големи количества записи, се препоръчва да използвате оператори на SQL вместо методите на тази услуга.

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

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

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

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

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

В Basic

В следващия пример се създава Dataset от таблицата Customers, съхранявана във файл на база от данни.


    oDatabase = CreateScriptService("Database", "C:\MyDatabase.odb")
    oDataset = oDatabase.CreateDataset("Customers")
    With oDataset
        Do While .MoveNext()
            oValues = .Values()
            ' ...
        Loop
        .CloseDataset()
    End With

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

В следващия пример се създава екземпляр на Dataset чрез филтриране на първоначалния набор от данни.


    oNewDataset = oDataset.CreateDataset(Filter := "[City]='New York'")

В Python


    database = CreateScriptService("Database", r"C:\MyDatabase.odb")
    dataset = database.CreateDataset("Customers")
    while dataset.MoveNext():
        values = dataset.Values
        # ...
    dataset.CloseDataset()


    new_dataset = dataset.CreateDataset(filter = "[City]='Ню Йорк'")

Свойства

Име	Само за четене	Тип	Описание
BOF	Не	Boolean	Връща True, ако указателят за текущ запис сочи преди първия запис в набора от данни, в противен случай връща False. Задайте на това свойство стойност True, за да преместите курсора в началото на набора от данни. Задаването на стойност False се игнорира.
DefaultValues	Да	Услуга Dictionary	Връща речник (Dictionary) с подразбираните стойности, използвани за всяко поле в набора от данни. Полетата или колоните в набора от данни са ключовете на речника. Типовете на полетата от базата от данни се преобразуват до съответните типове данни на Basic/Python. Когато типът на полето не е дефиниран, подразбираната стойност е Null, ако полето допуска стойност null, или Empty.
EOF	Не	Boolean	Връща True, ако указателят за текущ запис сочи след последния запис в набора от данни, в противен случай връща False. Задайте на това свойство стойност True, за да преместите курсора в края на набора от данни. Задаването на стойност False се игнорира.
Fields	Да	Array	Връща масив (Array) с имената на всички полета в набора от данни.
Filter	Да	String	Връща филтъра, приложен в допълнение към евентуалната клауза WHERE в първоначалния оператор на SQL. Това свойство е под формата на клауза WHERE без ключовата дума WHERE.
OrderBy	Да	String	Връща клаузата за сортиране, която замества евентуалната клауза ORDER BY, присъстваща в първоначалния оператор на SQL. Това свойство е под формата на клауза ORDER BY без ключовата дума ORDER BY.
ParentDatabase	Да	Услуга Database	Връща екземпляра на услугата Database, съответстващ на родителската база от данни на текущия набор от данни.
RowCount	Да	Long	Връща точния брой на записите в набора от данни. Обърнете внимание, че изчисляването на това свойство изисква преглеждане на целия набор от данни, което може да е трудоемко в зависимост от размера му.
RowNumber	Да	Long	Връща номера на текущия запис, започвайки от 1. Връща 0, ако това свойство е неизвестно.
Source	Да	String	Връща източника на набора от данни. Той може да бъде име на таблица, име на заявка или оператор на SQL.
SourceType	Да	String	Връща източника на набора от данни. Той може да бъде една от следните стойности низове:TABLE, QUERY или SQL.
UpdatableFields	Да	Array	Връща масив (Array) с имената на полетата в набора от данни, чието съдържание може да бъде променяно.
Values	Да	Array	Връща речник (Dictionary) с двойките (име на поле: стойност) на текущия запис в набора от данни.
XRowSet	Да	UNO обект	Връща UNO обекта от типа com.sun.star.sdb.RowSet, който представя набора от данни.

Списък с методи на услугата Dataset
CloseDataset CreateDataset Delete ExportValueToFile GetRows	GetValue Insert MoveFirst MoveLast	MoveNext MovePrevious Reload Update

CloseDataset

Затваря текущия набор от данни. Този метод връща True при успешно изпълнение.

Препоръчва наборът от данни да се затваря след употреба, за да се освободят ресурси.

Синтаксис:

svc.CloseDataset(): bool

Пример:

В Basic


      oDataset = oDatabase.CreateDataset("MyTable")
      ' ...
      oDataset.CloseDataset()

В Python


      dataset = database.CreateDataset("MyTable")
      # ...
      dataset.CloseDataset()

CreateDataset

Връща екземпляр на услугата Dataset от съществуващ набор от данни чрез прилагане на указания филтър и клауза ORDER BY.

Синтаксис:

svc.CreateDataset(opt filter: str, opt orderby: str): svc

Параметри:

filter: указва условието, на което трябва да отговарят записите, за да бъдат включени в резултатния набор. Този аргумент е във вида на клауза WHERE на SQL без ключовата дума WHERE. Ако той не е зададен, се прилага филтърът, използван в текущия набор от данни, в противен случай текущият филтър се замества с този аргумент.

orderby: указва подреждането на набора от данни като клауза ORDER BY на SQL без ключовата дума ORDER BY. Ако той не е зададен, се прилага редът на сортиране, използван в текущия набор от данни, в противен случай текущият ред на сортиране се замества с този аргумент.

Пример:

В Basic


      ' Използваме празен низ, за да премахнем текущия филтър.
      oNewDataset = oDataset.CreateDataset(Filter := "")
      ' Примери за често използвани филтри
      oNewDataset = oDataset.CreateDataset(Filter := "[Name] = 'Джон'")
      oNewDataset = oDataset.CreateDataset(Filter := "[Name] LIKE 'A'")
      ' Възможно е да се добавят допълнителни условия към текущия филтър.
      oNewDataset = oDataset.CreateDataset(Filter := "(" & oDataset.Filter & ") AND [Name] LIKE 'A'")

В Python


      new_dataset = dataset.CreateDataset(filter = "")
      new_dataset = dataset.CreateDataset(filter = "[Name] = 'Джон'")
      new_dataset = dataset.CreateDataset(filter = "[Name] LIKE 'A'")
      new_dataset = dataset.CreateDataset(filter = f"({dataset.Filter}) AND [Name] LIKE 'A'")

Delete

Изтрива текущия запис в набора от данни. Този метод връща True при успешно изпълнение.

След тази операция курсорът се позиционира върху записа непосредствено след изтрития. Ако изтритият запис е последен в набора от данни, курсорът се разполага след него и свойството EOF връща True.

Синтаксис:

svc.Delete(): bool

Пример:

В Basic


      oDataset.Delete()

В Python


      dataset.Delete()

ExportValueToFile

Експортира стойността на двоично поле от текущия запис в зададения файл.

Ако указаното поле не е двоично или не съдържа данни, резултатният файл не се създава.

Синтаксис:

svc.ExportValueToFile(fieldname: str, filename: str, overwrite: bool): bool

Параметри:

fieldname: името на двоичното поле, което да се експортира, като чувствителен към регистъра низ.

filename: пълният път към файла, който да бъде създаден, с нотацията, дефинирана в свойството FileSystem.FileNaming.

overwrite: задайте на този аргумент стойност True, за да позволите файлът местоназначение да бъде презаписан (подразбира се False).

Пример:

В примера по-долу наборът от данни съдържа поле с име Picture, което трябва да бъде експортирано като файл с изображение.

В Basic


      oDataset.ExportValueToFile("Picture", "C:\моето_изображение.png", True)

В Python


      dataset.ExportValueToFile("Picture", r"C:\моето_изображение.png", True)

GetRows

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

След изпълнението курсорът се позиционира върху реда, който е бил прочетен последен, или след последния запис в набора от данни, в който случай свойството EOF връща True.

Този метод може да се използва за четене на данни от набора блок по блок, като размерът на блока се определя от аргумента maxrows.

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

Синтаксис:

svc.GetRows(header: bool, maxrows: int): any

Параметри:

header: задайте на този аргумент стойност True, ако искате първият елемент на обекта от тип Array да съдържа заглавията на колони (подразбира се False).

maxrows: определя максималния брой върнати записи. Ако броят на съществуващите записи е по-малък от maxrows, размерът на върнатия масив ще бъде равен на броя на оставащите записи в набора от данни. Оставете този аргумент празен или му задайте стойност нула, за да бъдат върнати всички записи в набора от данни (подразбира се 0).

Пример:

Следващият пример чете набор от данни на блокове от 100 реда, докато бъде прочетен целият набор.

В Basic


      Dim arrChunk As Variant, lMaxRows As Long
      lMaxRows = 100
      Do
          arrChunk = oDataset.GetRows(MaxRows := lMaxRows)
          If UBound(arrChunk, 1) >= 0 Then
              ' ...
          End If
      Loop Until UBound(arrChunk, 1) < lMaxRows - 1

В Python


      max_rows = 100
      chunk = dataset.GetRows(maxrows = max_rows)
      while len(chunk) > 0:
          # ...
          chunk = dataset.GetRows(maxrows = max_rows)

GetValue

Връща стойността на указаното поле от текущия запис на набора от данни.

Ако указаното поле е двоично, се връща дължината му.

Синтаксис:

svc.GetValue(fieldname: str): any

Параметри:

fieldname: The name of the field to be returned, as a case-sensitive string.

Пример:

В Basic


      currId = oDataset.GetValue(FieldName := "ID")

В Python


      curr_id = dataset.GetValue(fieldname = "ID")

Insert

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

Ако първичният ключ на набора от данни е автостойност, този метод връща стойността на първичния ключ на новия запис. Иначе методът връща 0 (при успешно изпълнение) или -1 (при неуспех).

Обновяемите полета с незададени стойности се инициализират с подразбираните си стойности.

Ако указаното поле е двоично, се връща дължината му.

Синтаксис:

svc.Insert(pvargs: any): int

Параметри:

pvargs: речник (Dictionary) с двойки от имена на полета и съответните стойности. Също така може да се зададат четен брой аргументи, като се редуват имена на полета (тип String) и техните стойности.

Пример:

В Basic

Да си представим таблица с клиенти, наречена Customers, с 4 полета: ID (BigInt, автостойност и първичен ключ), Name (VarChar, име), Age (Integer, възраст) и City (VarChar, град).

Долният примерен код вмъква нов запис в този набор от данни с помощта на обект Dictionary.


      oDataset = oDatabase.CreateDataset("Customers")
      oNewData = CreateScriptService("Dictionary")
      oNewData.Add("Name", "Джон")
      oNewData.Add("Age", 50)
      oNewData.Add("City", "Чикаго")
      lNewID = oDataset.Insert(oNewData)

Същият резултат може да се постигне чрез подаване на всички двойки от поле и стойност като аргументи:


      oDataset.Insert("Name", "Джон", "Age", 50, "City", "Чикаго")

В Python


      dataset = database.CreateDataset("Customers")
      new_data = {"Name": "Джон", "Age": 30, "City": "Чикаго"}
      new_id = dataset.Insert(new_data)

Следните извиквания са допустими в Python:


      dataset.Insert("Name", "Джон", "Age", 50, "City", "Чикаго")
      dataset.Insert(Name = "Джон", Age = 50, City = "Чикаго")

MoveFirst / MoveLast

Премества курсора на набора от данни върху първия (MoveFirst) или последния (MoveLast) запис.

Този метод връща True при успешно изпълнение.

Този метод игнорира изтритите записи.

Синтаксис:

svc.MoveFirst(): bool

svc.MoveLast(): bool

Пример:

В Basic


      oDataset.MoveFirst()

В Python


      dataset.MoveFirst()

MoveNext / MovePrevious

Премества курсора на набора от данни напред (MoveNext) или назад (MovePrevious) с даден брой записи.

Този метод връща True при успешно изпълнение.

Този метод игнорира изтритите записи.

Синтаксис:

svc.MoveNext(offset: int = 1): bool

svc.MovePrevious(offset: int = 1): bool

Параметри:

offset: броят записи, с които курсорът да бъде преместен напред или назад. Този аргумент може да е отрицателна стойност (подразбира се 1).

Пример:

В Basic


      oDataset.MoveNext()
      oDataset.MoveNext(5)

В Python


      dataset.MoveNext()
      dataset.MoveNext(5)

Reload

Презарежда набора от данни от базата от данни. При извикване на този метод могат да бъдат зададени свойствата Filter и OrderBy.

Този метод връща True при успешно изпълнение.

Презареждането на набора от данни е полезно, когато в базата от данни са били вмъкнати или изтрити записи. Обърнете внимание, че методите CreateDataset и Reload изпълняват сходни функции, но Reload използва същия екземпляр на класа Dataset.

Синтаксис:

svc.Reload(opt filter: str, opt orderby: str): bool

Параметри:

Пример:

В Basic


      oDataset.Reload()
      oDataset.Reload(Filter := "[Name] = 'Джон'", OrderBy := "Age")

В Python


      dataset.Reload()
      dataset.Reload(Filter = "[Name] = 'Джон'", OrderBy = "Age")

Update

Обновява стойностите на указаните полета в текущия запис.

Този метод връща True при успешно изпълнение.

Синтаксис:

svc.Update(pvargs: any): bool

Параметри:

Пример:

В Basic

Долният примерен код обновява текущия запис с помощта на обект Dictionary.


      oNewValues = CreateScriptService("Dictionary")
      oNewValues.Add("Age", 51)
      oNewValues.Add("City", "Ню Йорк")
      oDataset.Update(oNewValues)

Същият резултат може да се постигне чрез подаване на всички двойки от поле и стойност като аргументи:


      oDataset.Update("Age", 51, "City", "Ню Йорк")

В Python


      new_values = {"Age": 51, "City": "Ню Йорк"}
      dataset.Update(new_values)


      dataset.Update("Age", 51, "City", "Ню Йорк")
      dataset.Update(Age = 51, City = "Ню Йорк")

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

Услуга SFDatabases.Database