Služba SFDatabases.Dataset

Služba Dataset se používá k tomu, aby reprezentovala tabulková data z databáze. Pomocí této služby je možné:

• Procházet datovou sadu a přistupovat k jejím datům.

• V datové sadě aktualizovat, vkládat a odstraňovat záznamy.

Aktualizace a vkládání záznamů pomocí služby Dataset je pomalejší než použití SQL příkazů. Při aktualizaci nebo vkládání značného množství záznamů je doporučeno použít SQL příkazy místo metod této služby.

Volání služby

Před používáním služby Dataset je nutné načíst či naimportovat knihovnu ScriptForge pomocí:

• V makrech Basicu je nutné načíst knihovnu ScriptForge následujícím příkazem:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Ve skriptech Pythonu je nezbytné import z modulu scriptforge:
from scriptforge import CreateScriptService

Instance služby Dataset je vytvořena metodou CreateDataset, kterou lze zavolat buď z instance služby Database, nebo z jiné instance služby Dataset.

V následujících příkladech je instance služby Dataset vytvořena z tabulky „Customers“ uložené v databázovém souboru.

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

Po vytvoření instance Dataset je aktuální pozice záznamu nastavena před první záznam.

V následujícím příkladu se vytvoří instance služby Dataset filtrováním původní datové sady.

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

Vlastnosti

CloseDataset

Zavře aktuální datovou sadu. V případě úspěšného uzavření vrátí metoda True.

Po použití se doporučuje datovou sadu uzavřít kvůli uvolnění zdrojů.

svc.CloseDataset(): bool

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

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

CreateDataset

Vrátí instanci služby Dataset ze stávající datové sady po použití zadaných příkazů pro filtrování a řazení.

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

filter: Určuje podmínku, kterou musí záznamy splňovat, aby byly zahrnuty do vrácené datové sady. Tento argument je vyjádřen jako SQL příkaz WHERE bez klíčového slova „WHERE“. Pokud tento argument není zadán, použije se filtr aktuální datové sady, v opačném případě bude tento aktuální filtr nahrazen tímto argumentem.

orderby: Určuje řazení datové sady jako SQL příkaz ORDER BY bez klíčového slova „ORDER BY“. Pokud tento argument není zadán, použije se řazení aktuální datové sady, v opačném případě bude toto aktuální řazení nahrazeno tímto argumentem.

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

      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

Smaže z datové sady aktuální záznam. V případě úspěšného smazání metoda vrátí True.

Po této operaci se ukazatel umístí na záznam bezprostředně následující za smazaným záznamem. Pokud je smazaný záznam posledním v datové sadě, ukazatel se umístí za něj a vlastnost EOF se nastaví na True.

svc.Delete(): bool

      oDataset.Delete()
    

      dataset.Delete()
    

ExportValueToFile

Vyexportuje hodnotu binární pole aktuálního záznamu do zadaného souboru.

Jestliže zadané pole není binární nebo neobsahuje žádná data, výstupní soubor se nevytvoří.

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

fieldname: Název binárního pole, které se má vyexportovat, jako řetězec, u něhož se rozlišuje velikost písmen.

filename: Úplná cesta k souboru, který se má vytvořit, v zápisu určeném vlastností FileSystem.FileNaming.

overwrite: Nastavte tento argument na True, chcete-li umožnit přepsání cílového souboru (výchozí = False).

V následujícím příkladu obsahuje datová sada pole pojmenované „Picture“, které by se mělo vyexportovat do souboru s obrázkem.

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

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

GetRows

Vrátí hodnoty datové sady ve dvourozměrném poli začínajícím od prvního záznamu po aktuálním záznamu.

Po vykonání se ukazatel umístí na řádek, který byl naposledy přečten, nebo za poslední záznam datové sady, přičemž se vlastnost EOF nastaví na hodnotu True.

Tuto metodu je možné použít pro čtení dat z datové sady po částech, jejichž velikost je určena argumentem maxrows.

Vrácené pole bude mít vždy dva rozměry, a to i tehdy, když datová sada obsahuje jediný sloupec a jediný záznam.

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

header: Nastavte tento argument na True, chcete-li, aby první položka Array obsahovala záhlaví sloupců (výchozí = False).

maxrows: Určuje maximální počet vrácených záznamů. Jestliže je počet existujících záznamů menší, velikost vráceného pole bude odpovídat počtu zbývajících záznamů v datové sadě. Chcete-li vrátit všechny řádky datové sady, ponechte tento argument prázdný nebo jej nastavte na nulu (výchozí = 0).

V následujícím příkladu je čtena celá datová sada, a to postupně po částech o 100 řádcích.

      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

Vrátí z aktuálního záznamu datové sady hodnotu zadaného pole.

Jestliže je zadané pole binární, vrátí se jeho délka.

svc.GetValue(fieldname: str): any

fieldname: Název pole, které se má vrátit, jako řetězec, u něhož se rozlišuje velikost písmen.

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

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

Insert

Vloží na konec datové sady nový záznam a inicializuje jeho pole zadanými hodnotami.

Pokud má primární klíč datové sady automatickou hodnotu, vrátí tato metoda hodnotu primárního klíče nového záznamu. V opačném případě vrátí 0 (v případě úspěšného vložení) nebo -1 (v případě neúspěšného vložení).

Pole, která lze aktualizovat, ale nemají zadané hodnoty, budou inicializována výchozími hodnotami.

Jestliže je zadané pole binární, vrátí se jeho délka.

svc.Insert(pvargs: any): int

pvargs: Dictionary obsahující dvojice názvů polí a jejich hodnot. Alternativně je možné zadat sudý počet argumentů představujících názvy polí (typu String) a jejich hodnoty.

Tabulka s názvem „Customers“ má 4 pole: „ID“ (BigInt, automatická hodnota a primární klíč), „Name“ (VarChar), „Age“ (Integer) a „City“ (VarChar).

V následujícím příkladu se do této datové sady vloží nový záznam pomocí Dictionary.

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

Téhož výsledku je možné dosáhnout předáním všech dvojic polí a hodnot:

      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)
    

V Pythonu je možné použít následující volání:

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

MoveFirst / MoveLast

Přesune ukazatel v datové sadě na první (u MoveFirst) nebo na poslední (u MoveLast) záznam.

V případě úspěšného přesunutí vrátí metoda True.

Tato metoda ignoruje smazané záznamy.

svc.MoveFirst(): bool

svc.MoveLast(): bool

      oDataset.MoveFirst()
    

      dataset.MoveFirst()
    

MoveNext / MovePrevious

Přesune ukazatel v datové sadě o zadaný počet záznamů vpřed (u MoveNext) nebo vzad (u MovePrevious).

V případě úspěšného přesunutí vrátí metoda True.

Tato metoda ignoruje smazané záznamy.

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

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

offset: Počet záznamů, o který se má ukazatel přesunout vpřed nebo vzad. Tento argument může být záporný (výchozí = 1).

      oDataset.MoveNext()
      oDataset.MoveNext(5)
    

      dataset.MoveNext()
      dataset.MoveNext(5)
    

Reload

Znovu načte datovou sadu z databáze. Při volání této metody lze určit vlastnosti Filter a OrderBy.

V případě úspěšného načtení vrátí metoda True.

Opětovné načtení je užitečné, jestliže byly do databáze vloženy nebo z ní odstraněny záznamy. Metody CreateDataset a Reload provádějí podobné operace, metoda Reload však znovu používá stejnou instanci třídy Dataset.

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

filter: Určuje podmínku, kterou musí záznamy splňovat, aby byly zahrnuty do vrácené datové sady. Tento argument je vyjádřen jako SQL příkaz WHERE bez klíčového slova „WHERE“. Pokud tento argument není zadán, použije se filtr aktuální datové sady, v opačném případě bude tento aktuální filtr nahrazen tímto argumentem.

orderby: Určuje řazení datové sady jako SQL příkaz ORDER BY bez klíčového slova „ORDER BY“. Pokud tento argument není zadán, použije se řazení aktuální datové sady, v opačném případě bude toto aktuální řazení nahrazeno tímto argumentem.

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

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

Update

Aktualizuje v aktuálním záznamu hodnoty zadaných polí.

V případě úspěšné aktualizace vrátí metoda True.

svc.Update(pvargs: any): bool

pvargs: Dictionary obsahující dvojice názvů polí a jejich hodnot. Alternativně je možné zadat sudý počet argumentů představujících názvy polí (typu String) a jejich hodnoty.

V následujícím příkladu je aktuální záznam aktualizován pomocí Dictionary.

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

Téhož výsledku je možné dosáhnout předáním všech dvojic polí a hodnot:

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

Všechny procedury nebo identifikátory knihovny ScriptForge, které jsou uvozeny podtržítkem "_", jsou určeny pro interní použití. Není zamýšleno je používat v makrech Basicu nebo skriptech Pythonu.