Помощ за LibreOffice 25.2
Услугата Dataset служи за представяне на таблични данни, предоставени от база от данни. Тази услуга позволява:
навигация в набор от данни и достъп до данните в него;
променяне, вмъкване и премахване на записи в набор от данни.
Променянето и вмъкването на записи чрез услугата Dataset е по-бавно, отколкото чрез оператори на SQL. Когато променяте или вмъквате големи количества записи, се препоръчва да използвате оператори на SQL вместо методите на тази услуга.
Преди да използвате услугата Dataset, библиотеката ScriptForge трябва да бъде заредена или импортирана:
Услугата Dataset се извиква чрез метода CreateDataset, който може да бъде извикан или от екземпляр на услугата Database, или от друг екземпляр на Dataset.
В следващия пример се създава 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'")
  
    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 | ||
|---|---|---|
Затваря текущия набор от данни. Този метод връща True при успешно изпълнение.
Препоръчва наборът от данни да се затваря след употреба, за да се освободят ресурси.
svc.CloseDataset(): bool
      oDataset = oDatabase.CreateDataset("MyTable")
      ' ...
      oDataset.CloseDataset()
    
      dataset = database.CreateDataset("MyTable")
      # ...
      dataset.CloseDataset()
    Връща екземпляр на услугата Dataset от съществуващ набор от данни чрез прилагане на указания филтър и клауза ORDER BY.
svc.CreateDataset(opt filter: str, opt orderby: str): svc
filter: указва условието, на което трябва да отговарят записите, за да бъдат включени в резултатния набор. Този аргумент е във вида на клауза WHERE на SQL без ключовата дума WHERE. Ако той не е зададен, се прилага филтърът, използван в текущия набор от данни, в противен случай текущият филтър се замества с този аргумент.
orderby: указва подреждането на набора от данни като клауза ORDER BY на SQL без ключовата дума ORDER BY. Ако той не е зададен, се прилага редът на сортиране, използван в текущия набор от данни, в противен случай текущият ред на сортиране се замества с този аргумент.
      ' Използваме празен низ, за да премахнем текущия филтър.
      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'")
    
      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'")
    Изтрива текущия запис в набора от данни. Този метод връща True при успешно изпълнение.
След тази операция курсорът се позиционира върху записа непосредствено след изтрития. Ако изтритият запис е последен в набора от данни, курсорът се разполага след него и свойството EOF връща True.
svc.Delete(): bool
      oDataset.Delete()
    
      dataset.Delete()
    Експортира стойността на двоично поле от текущия запис в зададения файл.
Ако указаното поле не е двоично или не съдържа данни, резултатният файл не се създава.
svc.ExportValueToFile(fieldname: str, filename: str, overwrite: bool): bool
fieldname: името на двоичното поле, което да се експортира, като чувствителен към регистъра низ.
filename: пълният път към файла, който да бъде създаден, с нотацията, дефинирана в свойството FileSystem.FileNaming.
overwrite: задайте на този аргумент стойност True, за да позволите файлът местоназначение да бъде презаписан (подразбира се False).
В примера по-долу наборът от данни съдържа поле с име Picture, което трябва да бъде експортирано като файл с изображение.
      oDataset.ExportValueToFile("Picture", "C:\моето_изображение.png", True)
    
      dataset.ExportValueToFile("Picture", r"C:\моето_изображение.png", True)
    Връща съдържанието на набора от данни като двуизмерен масив, започвайки от първия запис след текущия.
След изпълнението курсорът се позиционира върху реда, който е бил прочетен последен, или след последния запис в набора от данни, в който случай свойството EOF връща True.
Този метод може да се използва за четене на данни от набора блок по блок, като размерът на блока се определя от аргумента maxrows.
Връщаният масив винаги ще има две измерения, дори ако наборът от данни съдържа една колона и един запис.
svc.GetRows(header: bool, maxrows: int): any
header: задайте на този аргумент стойност True, ако искате първият елемент на обекта от тип Array да съдържа заглавията на колони (подразбира се False).
maxrows: определя максималния брой върнати записи. Ако броят на съществуващите записи е по-малък от maxrows, размерът на върнатия масив ще бъде равен на броя на оставащите записи в набора от данни. Оставете този аргумент празен или му задайте стойност нула, за да бъдат върнати всички записи в набора от данни (подразбира се 0).
Следващият пример чете набор от данни на блокове от 100 реда, докато бъде прочетен целият набор.
      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
    
      max_rows = 100
      chunk = dataset.GetRows(maxrows = max_rows)
      while len(chunk) > 0:
          # ...
          chunk = dataset.GetRows(maxrows = max_rows)
    Връща стойността на указаното поле от текущия запис на набора от данни.
Ако указаното поле е двоично, се връща дължината му.
svc.GetValue(fieldname: str): any
fieldname: името на полето, което да бъде върнато, като чувствителен към регистъра низ.
      currId = oDataset.GetValue(FieldName := "ID")
    
      curr_id = dataset.GetValue(fieldname = "ID")
    Вмъква нов запис в края на набора от данни и инициализира полетата му със зададените стойности.
Ако първичният ключ на набора от данни е автостойност, този метод връща стойността на първичния ключ на новия запис. Иначе методът връща 0 (при успешно изпълнение) или -1 (при неуспех).
Обновяемите полета с незададени стойности се инициализират с подразбираните си стойности.
Ако указаното поле е двоично, се връща дължината му.
svc.Insert(pvargs: any): int
pvargs: речник (Dictionary) с двойки от имена на полета и съответните стойности. Също така може да се зададат четен брой аргументи, като се редуват имена на полета (тип String) и техните стойности.
Да си представим таблица с клиенти, наречена 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", "Чикаго")
    
      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) запис.
Този метод връща True при успешно изпълнение.
Този метод игнорира изтритите записи.
svc.MoveFirst(): bool
svc.MoveLast(): bool
      oDataset.MoveFirst()
    
      dataset.MoveFirst()
    Премества курсора на набора от данни напред (MoveNext) или назад (MovePrevious) с даден брой записи.
Този метод връща True при успешно изпълнение.
Този метод игнорира изтритите записи.
svc.MoveNext(offset: int = 1): bool
svc.MovePrevious(offset: int = 1): bool
offset: броят записи, с които курсорът да бъде преместен напред или назад. Този аргумент може да е отрицателна стойност (подразбира се 1).
      oDataset.MoveNext()
      oDataset.MoveNext(5)
    
      dataset.MoveNext()
      dataset.MoveNext(5)
    Презарежда набора от данни от базата от данни. При извикване на този метод могат да бъдат зададени свойствата Filter и OrderBy.
Този метод връща True при успешно изпълнение.
Презареждането на набора от данни е полезно, когато в базата от данни са били вмъкнати или изтрити записи. Обърнете внимание, че методите CreateDataset и Reload изпълняват сходни функции, но Reload използва същия екземпляр на класа Dataset.
svc.Reload(opt filter: str, opt orderby: str): bool
filter: указва условието, на което трябва да отговарят записите, за да бъдат включени в резултатния набор. Този аргумент е във вида на клауза WHERE на SQL без ключовата дума WHERE. Ако той не е зададен, се прилага филтърът, използван в текущия набор от данни, в противен случай текущият филтър се замества с този аргумент.
orderby: указва подреждането на набора от данни като клауза ORDER BY на SQL без ключовата дума ORDER BY. Ако той не е зададен, се прилага редът на сортиране, използван в текущия набор от данни, в противен случай текущият ред на сортиране се замества с този аргумент.
      oDataset.Reload()
      oDataset.Reload(Filter := "[Name] = 'Джон'", OrderBy := "Age")
    
      dataset.Reload()
      dataset.Reload(Filter = "[Name] = 'Джон'", OrderBy = "Age")
    Обновява стойностите на указаните полета в текущия запис.
Този метод връща True при успешно изпълнение.
svc.Update(pvargs: any): bool
pvargs: речник (Dictionary) с двойки от имена на полета и съответните стойности. Също така може да се зададат четен брой аргументи, като се редуват имена на полета (тип String) и техните стойности.
Долният примерен код обновява текущия запис с помощта на обект Dictionary.
      oNewValues = CreateScriptService("Dictionary")
      oNewValues.Add("Age", 51)
      oNewValues.Add("City", "Ню Йорк")
      oDataset.Update(oNewValues)
    Същият резултат може да се постигне чрез подаване на всички двойки от поле и стойност като аргументи:
      oDataset.Update("Age", 51, "City", "Ню Йорк")
    
      new_values = {"Age": 51, "City": "Ню Йорк"}
      dataset.Update(new_values)
    
      dataset.Update("Age", 51, "City", "Ню Йорк")
      dataset.Update(Age = 51, City = "Ню Йорк")