Obsah

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

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

##### V Pythonu

        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

Název | Pouze pro čtení | Typ | Popis
--- | --- | --- | ---
BOF | ne | Boolean | Vrátí True, pokud je aktuální pozice záznamu před prvním záznamem datové sady. V opačném případě vrátí False. Nastavením této vlastnosti na True přesunete ukazatel na začátek datové sady. Nastavení na False se ignoruje.
DefaultValues | ano | služba Dictionary | Vrátí Dictionary s výchozími hodnotami použitými pro každé pole datové sady. Pole (sloupce) datové sady jsou klíči slovníku. Typy databázových polí se převádějí na odpovídající datové typy Basicu/Pythonu. Není-li typ pole definován, výchozí hodnotou je Null, pokud lze pole vynulovat, nebo Empty.
EOF | ne | Boolean | Vrátí True, pokud je aktuální pozice záznamu za posledním záznamem datové sady. V opačném případě vrátí False. Nastavením této vlastnosti na True přesunete ukazatel na konec datové sady. Nastavení na False se ignoruje.
Fields | ano | Array | Vrátí Array obsahující názvy všech polí datové sady.
Filter | ano | String | Vrátí filtr použitý spolu s případnými klauzulemi WHERE v inicializačním SQL příkazu. Tato vlastnost je vyjádřena jako klauzule WHERE bez klíčového slova „WHERE“.
OrderBy | ano | String | Vrátí klauzuli pro řazení, která případně nahrazuje klauzuli ORDER BY obsaženou v inicializačním SQL příkazu. Tato vlastnost je vyjádřena jako klauzule ORDER BY bez klíčových slov „ORDER BY“.
ParentDatabase | ano | služba Database | Vrátí instanci služby Database odpovídající rodičovské databázi pro aktuální datovou sadu.
RowCount | ano | Long | Vrátí přesný počet záznamů datové sady. Vyhodnocení této vlastnosti vyžaduje projití celé datové sady, což může být v závislosti na její velikosti náročné.
RowNumber | ano | Long | Vrátí číslo začínající od 1 pro aktuální záznam. Je-li tato vlastnost neznámá, vrátí 0.
Source | ano | String | Vrátí zdroj datové sady. Může se jednat o název tabulky, název dotazu nebo SQL příkaz.
SourceType | ano | String | Vrátí zdroj datové sady. Jedná se o některý z následujících řetězců:TABLE, QUERY nebo SQL.
UpdatableFields | ano | Array | Vrátí Array obsahující ty názvy polí datové sady, které lze aktualizovat.
Values | ano | Array | Vrátí Dictionary obsahující dvojice (název pole: hodnota) pro aktuální záznam datové sady.
XRowSet | ano | objekt UNO | Vrátí objekt UNO com.sun.star.sdb.RowSet představující datovou sadu.

Seznam metod služby Dataset
CloseDataset CreateDataset Delete ExportValueToFile GetRows | GetValue Insert MoveFirst MoveLast | MoveNext MovePrevious Reload Update

## 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ů.

### Syntaxe:

svc.CloseDataset(): bool

### Příklad:

##### V Basicu

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

##### V Pythonu

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

### Syntaxe:

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

### Parametry:

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.

### Příklad:

##### V Basicu

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

##### V Pythonu

          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.

### Syntaxe:

svc.Delete(): bool

### Příklad:

##### V Basicu

          oDataset.Delete()

##### V Pythonu

          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ří.

### Syntaxe:

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

### Parametry:

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

### Příklad:

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

##### V Basicu

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

##### V Pythonu

          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.

### Syntaxe:

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

### Parametry:

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

### Příklad:

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

##### V Basicu

          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

##### V Pythonu

          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.

### Syntaxe:

svc.GetValue(fieldname: str): any

### Parametry:

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

### Příklad:

##### V Basicu

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

##### V Pythonu

          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.

### Syntaxe:

svc.Insert(pvargs: any): int

### Parametry:

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.

### Příklad:

##### V Basicu

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

##### V Pythonu

          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.

### Syntaxe:

svc.MoveFirst(): bool

svc.MoveLast(): bool

### Příklad:

##### V Basicu

          oDataset.MoveFirst()

##### V Pythonu

          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.

### Syntaxe:

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

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

### Parametry:

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

### Příklad:

##### V Basicu

          oDataset.MoveNext()
          oDataset.MoveNext(5)

##### V Pythonu

          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.

### Syntaxe:

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

### Parametry:

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.

### Příklad:

##### V Basicu

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

##### V Pythonu

          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.

### Syntaxe:

svc.Update(pvargs: any): bool

### Parametry:

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.

### Příklad:

##### V Basicu

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

##### V Pythonu

          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.

Související témata

Služba SFDatabases.Database