Съдържание

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

### Пример:

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

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

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

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

### Пример:

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

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

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

### Пример:

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