Услуга SFDatabases.Dataset

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

warning

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


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

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

note

• Макросите на 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
  
note

При създаването на обекта от тип 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

Returns a Dictionary with the default values used for each field in the dataset. The fields or columns in the dataset are the keys in the 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 при успешно изпълнение.

note

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


Синтаксис:

svc.CloseDataset(): bool

Пример:

В Basic

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

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

CreateDataset

Returns a Dataset service instance from an existing dataset by applying the specified filter and order by statements.

Синтаксис:

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

Параметри:

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

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

Пример:

В Basic

      ' Use an empty string to remove the current filter
      oNewDataset = oDataset.CreateDataset(Filter := "")
      ' Examples of common filters
      oNewDataset = oDataset.CreateDataset(Filter := "[Name] = 'John'")
      oNewDataset = oDataset.CreateDataset(Filter := "[Name] LIKE 'A'")
      ' It is possible to append additional conditions to the current filter
      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

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

note

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


Синтаксис:

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.

note

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.

note

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).

note

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


note

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 при успешно изпълнение.

note

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 при успешно изпълнение.

note

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 при успешно изпълнение.

tip

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")
    
warning

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