Spis treści

# Usługa SFDatabases.Dataset

Usługa Dataset służy do reprezentowania danych tabelarycznych generowanych przez bazę danych. Dzięki tej usłudze możliwe jest:

- Nawigowanie i uzyskiwanie dostępu do danych w zestawie danych.

- Aktualizowanie, wstawianie i usuwanie rekordów w zestawie danych.

Aktualizowanie i wstawianie rekordów przy użyciu usługi Dataset jest wolniejsze niż przy użyciu instrukcji SQL. Przy aktualizacji lub wstawianiu dużej liczby rekordów zaleca się stosowanie instrukcji SQL zamiast stosowania metod zawartych w tej usłudze.

## Wywoływanie usługi

Przed skorzystaniem z usługi Dataset należy załadować lub zaimportować bibliotekę ScriptForge:

• Podstawowe makra wymagają załadowania biblioteki ScriptForge przy użyciu następującej instrukcji:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Skrypty Pythona wymagają importu z modułu scriptforge:
from scriptforge import CreateScriptService

Usługę Dataset wywołuje się za pomocą metody CreateDataset, którą można wywołać z instancji usługi Database lub z innej instancji Dataset.

##### W języku Basic

Poniższy przykład tworzy Dataset z tabeli "Customers" przechowywanej w pliku bazy danych.

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

Po utworzeniu Dataset bieżący rekord jest umieszczany przed pierwszym rekordem.

Poniższy przykład tworzy instancję Dataset poprzez filtrowanie oryginalnego zestawu danych.

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

##### W języku 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]='New York'")

## Właściwości

Nazwa | Tylko do odczytu | Typ | Opis
--- | --- | --- | ---
BOF | Nie | Boolean | Zwraca True, jeśli bieżąca pozycja rekordu znajduje się przed pierwszym rekordem w zbiorze danych, w przeciwnym razie zwraca False. Ustaw tę właściwość na True, aby przenieść kursor na początek zbioru danych. Ustawienie tej właściwości na False jest ignorowane.
DefaultValues | Tak | Usługa Dictionary | Zwraca Dictionary z wartościami domyślnymi używanymi dla każdego pola w zbiorze danych. Pola lub kolumny w zestawie danych są kluczami w słowniku. Typy pól bazy danych są konwertowane na odpowiadające im typy danych Basic/Python. Gdy typ pola jest niezdefiniowany, wartością domyślną jest Null, jeśli pole dopuszcza wartość null lub Empty.
EOF | Nie | Boolean | Zwraca True, jeśli bieżąca pozycja rekordu przypada po ostatnim rekordzie w zbiorze danych, w przeciwnym razie zwraca False. Ustaw tę właściwość na True, aby przenieść kursor na koniec zbioru danych. Ustawienie tej właściwości na False jest ignorowane.
Fields | Tak | Array | Zwraca Array zawierającą nazwy wszystkich pól w zbiorze danych.
Filter | Tak | String | Zwraca filtr zastosowany oprócz ewentualnych klauzul WHERE w początkowej instrukcji SQL. Ta właściwość jest wyrażona jako klauzula WHERE bez słowa kluczowego "WHERE".
OrderBy | Tak | String | Zwraca klauzulę porządkującą, która zastępuje ewentualną klauzulę ORDER BY obecną w początkowej instrukcji SQL. Ta właściwość jest wyrażona jako klauzula ORDER BY bez słów kluczowych "ORDER BY".
ParentDatabase | Tak | Usługa Database | Zwraca instancję Database odpowiadającą nadrzędnej bazie danych bieżącego zbioru danych.
RowCount | Tak | Long | Zwraca dokładną liczbę rekordów w zestawie danych. Należy pamiętać, że ocena tej właściwości wiąże się z przeglądaniem całego zbioru danych, co może być kosztowne w zależności od rozmiaru zbioru danych.
RowNumber | Tak | Long | Zwraca numer bieżącego rekordu, zaczynając od 1. Zwraca 0, jeśli ta właściwość jest nieznana.
Source | Tak | String | Zwraca źródło zbioru danych. Może to być nazwa tabeli, nazwa kwerendy lub instrukcja SQL.
SourceType | Tak | String | Zwraca źródło zbioru danych. Może to być jedna z następujących wartości ciągu: TABLE, QUERY lub SQL.
UpdatableFields | Tak | Array | Zwraca Array zawierającą nazwy pól zbioru danych, które można aktualizować.
Values | Tak | Array | Zwraca Dictionary zawierającą pary (nazwa pola: wartość) bieżącego rekordu w zbiorze danych.
XRowSet | Tak | Obiekt UNO | Zwraca obiekt UNO com.sun.star.sdb.RowSet reprezentujący zbiór danych.

Lista metod w usłudze Dataset
CloseDataset CreateDataset Delete ExportValueToFile GetRows | GetValue Insert MoveFirst MoveLast | MoveNext MovePrevious Reload Update

## CloseDataset

Zamyka bieżący zestaw danych. Ta metoda zwraca wartość True, jeśli operacja się powiedzie.

Zaleca się zamknięcie zbioru danych po jego wykorzystaniu w celu zwolnienia zasobów.

### Składnia:

svc.CloseDataset(): bool

### Przykład:

##### W języku Basic

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

##### W języku Python

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

## CreateDataset

Zwraca instancję usługi Dataset z istniejącego zbioru danych poprzez zastosowanie określonego filtru i uporządkowanie według instrukcji.

### Składnia:

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

### Parametry:

filter: określa warunek, który muszą spełnić rekordy, aby zostały uwzględnione w zwróconym zbiorze danych. Argument ten jest wyrażony jako instrukcja SQL WHERE bez słowa kluczowego "WHERE". Jeśli ten argument nie zostanie określony, zastosowany zostanie filtr użyty w bieżącym zbiorze danych, w przeciwnym razie bieżący filtr zostanie zastąpiony tym argumentem.

orderby: określa kolejność zbioru danych jako instrukcja SQL ORDER BY bez słowa kluczowego "ORDER BY". Jeśli ten argument nie zostanie określony, zostanie zastosowany porządek sortowania zastosowany w bieżącym zbiorze danych, w przeciwnym razie bieżący porządek sortowania zostanie zastąpiony tym argumentem.

### Przykład:

##### W języku 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'")

##### W języku Python

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

## Delete

Usuwa bieżący rekord ze zbioru danych. Ta metoda zwraca wartość True, jeśli operacja się powiedzie.

Po tej operacji kursor ustawia się na rekord bezpośrednio za usuniętym rekordem. Jeżeli usunięty rekord jest ostatnim w zbiorze danych, wówczas kursor zostaje umieszczony za nim, a właściwość EOF zwraca wartość True.

### Składnia:

svc.Delete(): bool

### Przykład:

##### W języku Basic

          oDataset.Delete()

##### W języku Python

          dataset.Delete()

## ExportValueToFile

Eksportuje wartość pola binarnego bieżącego rekordu do określonego pliku.

Jeśli podane pole nie jest binarne lub nie zawiera żadnych danych, plik wyjściowy nie zostanie utworzony.

### Składnia:

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

### Parametry:

fieldname: nazwa pola binarnego, które ma zostać wyeksportowane, jako ciąg znaków, w którym rozróżniana jest wielkość liter.

filename: pełna ścieżka do pliku, który ma zostać utworzony, przy użyciu notacji zdefiniowanej we właściwości FileSystem.FileNaming.

overwrite: ustaw ten argument na True, aby umożliwić nadpisanie pliku docelowego (domyślnie = False).

### Przykład:

W poniższym przykładzie zbiór danych zawiera pole o nazwie "Picture", które należy wyeksportować do pliku obrazu.

##### W języku Basic

          oDataset.ExportValueToFile("Picture", "C:\my_image.png", True)

##### W języku Python

          dataset.ExportValueToFile("Picture", r"C:\my_image.png", True)

## GetRows

Zwraca zawartość zestawu danych w dwuwymiarowej tablicy, zaczynając od pierwszego rekordu po bieżącym rekordzie.

Po wykonaniu kursor jest ustawiany w wierszu, który był ostatnio odczytany, lub za ostatnim rekordem w zbiorze danych, w którym to przypadku właściwość EOF zwraca wartość True.

Metodą tą można odczytywać dane ze zbioru w porcjach, których rozmiar jest definiowany za pomocą argumentu maxrows.

Zwrócona tablica będzie zawsze miała dwa wymiary, nawet jeśli zbiór danych zawiera jedną kolumnę i jeden rekord.

### Składnia:

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

### Parametry:

header: ustaw ten argument na True, aby pierwszy wpis w Array zawierał główki kolumn (domyślnie = False).

maxrows: określa maksymalną liczbę zwracanych rekordów. Jeśli liczba istniejących rekordów jest mniejsza niż maxrows, wówczas rozmiar zwróconej tablicy będzie równy liczbie pozostałych rekordów w zbiorze danych. Pozostaw ten argument pusty lub ustaw go na zero, aby zwrócić wszystkie wiersze w zbiorze danych (domyślnie = 0).

### Przykład:

Poniższy przykład odczytuje zestaw danych w fragmentach po 100 wierszy, aż do momentu odczytania całego zestawu danych.

##### W języku 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

##### W języku Python

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

## GetValue

Zwraca wartość określonego pola z bieżącego rekordu zbioru danych.

Jeżeli podane pole jest binarne, zwracana jest jego długość.

### Składnia:

svc.GetValue(fieldname: str): any

### Parametry:

fieldname: nazwa pola, które ma zostać zwrócone, jako ciąg znaków, w którym rozróżniana jest wielkość liter.

### Przykład:

##### W języku Basic

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

##### W języku Python

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

## Insert

Wstawia nowy rekord na końcu zbioru danych i inicjuje jego pola określonymi wartościami.

Jeśli kluczem głównym zbioru danych jest wartość automatyczna, ta metoda zwraca wartość klucza głównego nowego rekordu. W przeciwnym razie metoda zwróci 0 (w przypadku powodzenia) lub -1 (w przypadku niepowodzenia).

Pola, które można aktualizować, z nieokreślonymi wartościami są inicjowane wartościami domyślnymi.

Jeżeli podane pole jest binarne, zwracana jest jego długość.

### Składnia:

svc.Insert(pvargs: any): int

### Parametry:

pvargs: Dictionary zawierająca pary nazw pól i ich wartości. Ewentualnie można określić parzystą liczbę argumentów, zmieniając nazwy pól (jako String) i ich wartości.

### Przykład:

##### W języku Basic

Rozważmy tabelę o nazwie "Customers" z 4 polami: "ID" (BigInt, wartość automatyczna i klucz główny), "Name" (VarChar), "Age" (Integer), "City" (VarChar).

Poniższy przykład wstawia nowy rekord do tego zbioru danych przy użyciu Dictionary.

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

Ten sam wynik można osiągnąć przekazując wszystkie pary pól i wartości jako argumenty:

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

##### W języku Python

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

W Pythonie akceptowane są następujące wywołania:

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

## MoveFirst / MoveLast

Przesuwa kursor zbioru danych do pierwszego (za pomocą MoveFirst) lub do ostatniego (za pomocą MoveLast) rekordu.

Ta metoda zwraca wartość True, jeśli operacja się powiedzie.

W przypadku tej metody usunięte rekordy są ignorowane.

### Składnia:

svc.MoveFirst(): bool

svc.MoveLast(): bool

### Przykład:

##### W języku Basic

          oDataset.MoveFirst()

##### W języku Python

          dataset.MoveFirst()

## MoveNext / MovePrevious

Przesuwa kursor zbioru danych do przodu (za pomocą MoveNext) lub do tyłu (za pomocą MovePrevious) o określoną liczbę rekordów.

Ta metoda zwraca wartość True, jeśli operacja się powiedzie.

W przypadku tej metody usunięte rekordy są ignorowane.

### Składnia:

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

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

### Parametry:

offset: liczba rekordów, o jaką należy przesunąć kursor do przodu lub do tyłu. Argument ten może mieć wartość ujemną (domyślnie = 1).

### Przykład:

##### W języku Basic

          oDataset.MoveNext()
          oDataset.MoveNext(5)

##### W języku Python

          dataset.MoveNext()
          dataset.MoveNext(5)

## Reload

Ponownie ładuje zestaw danych z bazy danych. Przy wywoływaniu tej metody można zdefiniować właściwości Filter i OrderBy.

Ta metoda zwraca wartość True, jeśli operacja się powiedzie.

Ponowne załadowanie zbioru danych jest przydatne, gdy rekordy zostały wstawione do bazy danych lub z niej usunięte. Należy pamiętać, że metody CreateDataset i Reload wykonują podobne funkcje, jednakże Reload ponownie wykorzystują tę samą instancję klasy Dataset.

### Składnia:

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

### Parametry:

filter: określa warunek, który muszą spełnić rekordy, aby zostały uwzględnione w zwróconym zbiorze danych. Argument ten jest wyrażony jako instrukcja SQL WHERE bez słowa kluczowego "WHERE". Jeśli ten argument nie zostanie określony, zastosowany zostanie filtr użyty w bieżącym zbiorze danych, w przeciwnym razie bieżący filtr zostanie zastąpiony tym argumentem.

orderby: określa kolejność zbioru danych jako instrukcja SQL ORDER BY bez słowa kluczowego "ORDER BY". Jeśli ten argument nie zostanie określony, zostanie zastosowany porządek sortowania zastosowany w bieżącym zbiorze danych, w przeciwnym razie bieżący porządek sortowania zostanie zastąpiony tym argumentem.

### Przykład:

##### W języku Basic

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

##### W języku Python

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

## Update

Zaktualizuj wartości określonych pól w bieżącym rekordzie.

Ta metoda zwraca wartość True, jeśli operacja się powiedzie.

### Składnia:

svc.Update(pvargs: any): bool

### Parametry:

pvargs: Dictionary zawierająca pary nazw pól i ich wartości. Ewentualnie można określić parzystą liczbę argumentów, zmieniając nazwy pól (jako String) i ich wartości.

### Przykład:

##### W języku Basic

Poniższy przykład aktualizuje bieżący rekord przy użyciu Dictionary.

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

Ten sam wynik można osiągnąć przekazując wszystkie pary pól i wartości jako argumenty:

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

##### W języku 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")

Wszystkie podstawowe procedury lub identyfikatory ScriptForge poprzedzone znakiem podkreślenia „_” są zarezerwowane do użytku wewnętrznego. Nie należy ich używać w makrach Basic ani skryptach Pythona.

Tematy pokrewne

Usługa SFDatabases.Database