Съдържание

# Услуга 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

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

After execution, the cursor is positioned at the row that was last read or after the last record in the dataset, in which case the EOF property returns True.

This method can be used to read data from the dataset in chunks, whose size is defined by the maxrows argument.

The returned array will always have two dimensions, even if the dataset contains a single column and a single record.

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

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

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

header: Set this argument to True to make the first entry in the Array contain the column headers (Default = False).

maxrows: Defines the maximum number of records to be returned. If the number of existing records is smaller than maxrows, then the size of the returned array will be equal to the number of remaining records in the dataset. Leave this argument blank or set it to zero to return all rows in the dataset (Default = 0)

### Пример:

The following example reads a dataset in chunks of 100 rows until all the dataset has been read.

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

Returns the value of the specified field from the current record of the dataset.

If the specified field is binary, then its length is returned.

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

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

Inserts a new record at the end of the dataset and initialize its fields with the specified values.

If the primary key of the dataset is an auto value, then this method returns the primary key value of the new record. Otherwise, the method will return 0 (when successful) or -1 (when not successful).

Updatable fields with unspecified values are initialized with their default values.

If the specified field is binary, then its length is returned.

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

svc.Insert(pvargs: any): int

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

pvargs: A Dictionary containing pairs of field names and their respective values. Alternatively, an even number of arguments can be specified alternating field names (as a String) and their values.

### Пример:

##### В Basic

Consider a table named "Customers" with 4 fields: "ID" (BigInt, auto value and primary key), "Name" (VarChar), "Age" (Integer), "City" (VarChar).

The example below inserts a new record into this dataset using a Dictionary.

          oDataset = oDatabase.CreateDataset("Customers")
          oNewData = CreateScriptService("Dictionary")
          oNewData.Add("Name", "John")
          oNewData.Add("Age", 50)
          oNewData.Add("City", "Chicago")
          lNewID = oDataset.Insert(oNewData)

The same result can be achieved by passing all pairs of fields and values as arguments:

          oDataset.Insert("Name", "John", "Age", 50, "City", "Chicago")

##### В Python

          dataset = database.CreateDataset("Customers")
          new_data = {"Name": "John", "Age": 30, "City": "Chicago"}
          new_id = dataset.Insert(new_data)

The following calls are accepted in Python:

          dataset.Insert("Name", "John", "Age", 50, "City", "Chicago")
          dataset.Insert(Name = "John", Age = 50, City = "Chicago")

## MoveFirst / MoveLast

Moves the dataset cursor to the first (with MoveFirst) or to the last (with MoveLast) record.

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

Deleted records are ignored by this method.

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

svc.MoveFirst(): bool

svc.MoveLast(): bool

### Пример:

##### В Basic

          oDataset.MoveFirst()

##### В Python

          dataset.MoveFirst()

## MoveNext / MovePrevious

Moves the dataset cursor forward (with MoveNext) or backwards (with MovePrevious) by a given number of records.

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

Deleted records are ignored by this method.

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

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

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

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

offset: The number of records by which the cursor shall be moved forward or backwards. This argument may be a negative value (Default = 1).

### Пример:

##### В Basic

          oDataset.MoveNext()
          oDataset.MoveNext(5)

##### В Python

          dataset.MoveNext()
          dataset.MoveNext(5)

## Reload

Reloads the dataset from the database. The properties Filter and OrderBy may be defined when calling this method.

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

Reloading the dataset is useful when records have been inserted to or deleted from the database. Note that the methods CreateDataset and Reload perform similar functions, however Reload reuses the same Dataset class instance.

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

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] = 'John'", OrderBy := "Age")

##### В Python

          dataset.Reload()
          dataset.Reload(Filter = "[Name] = 'John'", OrderBy = "Age")

## Update

Update the values of the specified fields in the current record.

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

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

svc.Update(pvargs: any): bool

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

pvargs: A Dictionary containing pairs of field names and their respective values. Alternatively, an even number of arguments can be specified alternating field names (as a String) and their values.

### Пример:

##### В Basic

The example below updates the current record using a Dictionary.

          oNewValues = CreateScriptService("Dictionary")
          oNewValues.Add("Age", 51)
          oNewValues.Add("City", "New York")
          oDataset.Update(oNewValues)

The same result can be achieved by passing all pairs of fields and values as arguments:

          oDataset.Update("Age", 51, "City", "New York")

##### В Python

          new_values = {"Age": 51, "City": "New York"}
          dataset.Update(new_values)

          dataset.Update("Age", 51, "City", "New York")
          dataset.Update(Age = 51, City = "New York")

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

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

Услуга SFDatabases.Database