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.

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

    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

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.

svc.CloseDataset(): bool

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

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

CreateDataset

Zwraca instancję usługi Dataset z istniejącego zbioru danych poprzez zastosowanie określonego filtru i instrukcji ORDER BY.

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

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.

      ' Użyj pustego ciągu, aby usunąć bieżący filtr
      oNewDataset = oDataset.CreateDataset(Filter := "")
      ' Przykłady popularnych filtrów
      oNewDataset = oDataset.CreateDataset(Filter := "[Name] = 'John'")
      oNewDataset = oDataset.CreateDataset(Filter := "[Name] LIKE 'A'")
      ' Do aktualnego filtra można dodać dodatkowe warunki
      oNewDataset = oDataset.CreateDataset(Filter := "(" & oDataset.Filter & ") AND [Name] LIKE 'A'")
    

      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.

svc.Delete(): bool

      oDataset.Delete()
    

      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.

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

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

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

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

      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.

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

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

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

      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)
    

GetValue

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

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

svc.GetValue(fieldname: str): any

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

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

      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ść.

svc.Insert(pvargs: any): int

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.

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

      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.

svc.MoveFirst(): bool

svc.MoveLast(): bool

      oDataset.MoveFirst()
    

      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.

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

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

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

      oDataset.MoveNext()
      oDataset.MoveNext(5)
    

      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.

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

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.

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

      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.

svc.Update(pvargs: any): bool

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.

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

      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.