Wobsah

# Słužba SFDatabases.Dataset

Słužba Dataset so wužiwa, zo by tabelariske daty reprezentowała, kotrež su so přez datowu banku wutworili. Z tutej słužbu je móžno:

- Po datach w datowym wobstatku nawigěrować a přistup k nim dóstać.

- Datowe sadźby w datowym wobstatku aktualizować, zasadźić a wotstronić.

Aktualizowanje a zasadźowanje datowych sadźbow z pomocu słužby Dataset je pomałši hač wužiwanje SQL-přikazow. Hdyž so jara wjele datowych sadźbow aktualizuje abo zasadźuje, poruča so, SQL-přikazy město metodow w tutej słužbje wužiwać.

## Słužbowe wuwołanje

Před wužiwanjom słužby Dataset dyrbi so biblioteka ScriptForge začitać abo importować:

• Makra Basic sej wužaduja, zo so biblioteka ScriptForge z pomocu slědowaceho přikaza začituje:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Skripty Python sej import z modula scriptforge wužaduja:
from scriptforge import CreateScriptService

Słužba Dataset so z pomocu metody CreateDataset wuwołuje, kotraž da so pak ze słužboweje instancy Datebase pak z druheje instancy Dataset wuwołać.

##### W Basic

Slědowacy přikład Dataset z tabele „Kupcy“, kotraž je w dataji datoweje banki składowana.

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

Při wutworjenju Dataset so aktualna datowa sadźba před prěnjej datowej sadźbu pozicioněruje.

Slědowacy přikład instancu Dataset wutworja, hdyž so prěnjotny datowy wobstatk filtruje.

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

##### W Python

        database = CreateScriptService("Database", r"C:\MyDatabase.odb")
        dataset = database.CreateDataset("Kupcy")
        while dataset.MoveNext():
            values = dataset.Values
            # ...
        dataset.CloseDataset()

        new_dataset = dataset.CreateDataset(filter = "[City]='Budyšin'")

## Kajkosće

Mjeno | Přećiwo pisanju škitany | Typ | Wopisanje
--- | --- | --- | ---
BOF | Ně | Boolean | Wróći True, jeli pozicija aktualneje datoweje sadźby je před prěnjej datowej sadźbu w datowym wobstatku, hewak so False wróći. Stajće kajkosć na True, zo byšće kursor k spočatkej datoweho wobstatka pohibował. Stajenje tuteje kajkosće na False so ignoruje.
DefaultValues | Haj | Słužba Dictionary | Wróći Dictionary ze standardnymi hódnotami, kotrež so za kóžde polo w datowym wobstatku wužiwaja. Pola abo špalty w datowym wobstatku su kluče w słowniku. Pólne typy datoweje banki so do swojich wotpowědnych datowych typow Basic/Python přetworjeja. Hdyž pólny typ je njedefinowany, standardna hódnota je Null, jeli polo je nul abo Empty.
EOF | Ně | Boolean | Wróći True, jeli aktualna pozicija datoweje sadźby je za poslednjej datowej sadźbu w datowym wobstatku, hewak so False wróći. Stajće tutu kajkosć na True, zo byšće kursor ke kóncej datoweho wobstatka pohibował. Stajenje tuteje kajkosće na False so ignoruje.
Fields | Haj | Array | Wróći Array, kotraž mjena wšěch polow w datowym wobstatku wobsahuje.
Filter | Haj | String | Wróći filter, kotryž so přidatnje k ewentuelnym klawslan WHERE w spočatnym SQL-přikazu nałožuje. Tuta kajkosć so jako klawsla WHERE bjez klučoweho słowa „WHERE“ zwuraznja.
OrderBy | Haj | String | Wróći sortěrowansku klawslu, kotraž ewentuelne klawsle ORDER BY w spočatnym SQL-přikazu narunuje. Tuta kajkosć so jako klawsla ORDER BY bjez klučowych słowow „ORDER BY“ zwuraznja.
ParentDatabase | Haj | Słužba Database | Wróći instancu Database, kotraž nadrjadowanej datowej bance aktualneho datoweho wobstatka wotpowěduje.
RowCount | Haj | Long | Wróći eksaktnu ličbu datowych sadźbow w datowym wobstatku. Dźiwajće na to, zo wuhódnoćowanje tuteje kajkosće přepytowanje cyłeho datoweho wobstatka implikuje, štož móže wotwisujo wot wulkosće datoweho wobstatka čas rubjace być.
RowNumber | Haj | Long | Wróći čisło aktualneje datoweje sadźby započinajo z 1. Wróći 0, jeli tuta kajkosć je njeznata.
Source | Haj | String | Wróći žórło datoweho wobstatka. Móže pak mjeno tabele, wotprašowanja pak SQL-přikaz być.
SourceType | Haj | String | Wróći žórło datoweho wobstatka. Móže jedna ze slědowacych hódnotow być: TABLE, QUERY abo SQL.
UpdatableFields | Haj | Array | Wróći Array, kotraž mjena polow datoweho wobstatka wobsahuje, kotrež su aktualizujomne.
Values | Haj | Array | Wróći Dictionary, kotryž pory (pólne mjeno: hódnota) aktualneje datoweje sadźby w datowym wobstatku wobsahuje.
XRowSet | Haj | Objekt UNO | Wróći objekt UNO com.sun.star.sdb.RowSet, kotryž datowy wobstatk reprezentuje.

Lisćina metodow w słužbje Dataset
CloseDataset CreateDataset Delete ExportValueToFile GetRows | GetValue Insert MoveFirst MoveLast | MoveNext MovePrevious Reload Update

## CloseDataset

Začinja aktualny datowy wobstatk. Tuta metoda True wróći, hdyž je wuspěšna.

Poruča so, datowy wobstatk po jeho wužiwanje začinić, zo bychu so resursy wuswobodźili

### Syntaksa:

svc.CloseDataset(): bool

### Přikład:

##### W Basic

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

##### W Python

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

## CreateDataset

Wroći słužbowu instancu Dataset z eksistowaceho datoweho wobstatka, hdyž so podaty filter a přikazy ORDER BY nałožuja.

### Syntaksa:

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

### Parametry:

filter: Podawa wuměnjenje, kotremuž datowe sadźby dyrbja wotpowědować, zo bychu so do wróćeneho datoweho wobstatka zapřijeli. Tutón argument so jako SQL-přikat WHERE bjez klučoweho słowa „WHERE“ zwuraznja. Jeli tutón argument podaty njeje, so filter nałožuje, kotryž so w aktualnym datowym wobstatku wužiwa, hewak so aktualny filter z tutym argumentom wuměni.

orderby: Podawa porjad datoweho wobstatka jako SQL-přikaz ORDER BY bjez klučoweho słowa „ORDER BY“. Jeli tutón argument podaty njeje, so sortěrowanski porjad nałožuje, kotryž so w aktualnym wobstatku wužiwa, hewak so aktualny sortěrowanski porjad z tutym argumentom wuměni.

### Přikład:

##### W Basic

          ' Prózdny znamješkowy rjećazk wužiwać, zo by so aktualny filter wotstronił
          oNewDataset = oDataset.CreateDataset(Filter := "")
          ' Přikłady za rozšěrjene filtry
          oNewDataset = oDataset.CreateDataset(Filter := "[Name] = 'John'")
          oNewDataset = oDataset.CreateDataset(Filter := "[Name] LIKE 'A'")
          ' Je móžno, k aktualnemu filtrej přidatne wuměnjenja připowěsnyć
          oNewDataset = oDataset.CreateDataset(Filter := "(" & oDataset.Filter & ") AND [Name] LIKE 'A'")

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

Zhaša aktualnu datowu sadźbu z datoweho wobstatka. Tuta metoda True wróća, hdyž je wuspěšna.

Po tutej operaciji so kursor pola datoweje sadźby direktnje za zhašanej datowej sadźbu pozicioněruje. Jeli zhašana datowa sadźba je poslednja w datowym wobstatku, so kursor za njej pozicioněruje a kajkosć EOF True wróći.

### Syntaksa:

svc.Delete(): bool

### Přikład:

##### W Basic

          oDataset.Delete()

##### W Python

          dataset.Delete()

## ExportValueToFile

Eksportuje hódnotu binarneho pola aktualneje datowej sadźby podateje dataje.

Jeli podate polo binarne njeje abo jeli daty njewobsahuje, so wudawanska dataja njewutwori.

### Syntaksa:

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

### Parametry:

fieldname: Mjeno binarneho pola, kotrež so ma eksportować, jako znamješkowy rjećazk, kotryž na wulkopisanje dźiwa.

filename: Dospołna šćežka k dataji, kotraž so ma z pomocu notacije wutworić, kotraž je w kajkosći FileSystem.FileNaming definowana.

overwrite: Stajće tutón argument na True, zo byšće dowolił, zo so cilowa dataja přepisuje (standard = False).

### Přikład:

W slědowacym přikładźe datowy wobstatk polo z mjenom „Wobraz“ wobsahuje, kotrež ma so do wobrazoweje dataje eksportować.

##### W Basic

          oDataset.ExportValueToFile("Wobraz", "C:\mój_wobraz.png", True)

##### W Python

          dataset.ExportValueToFile("Wobraz", r"C:\mój_wobraz.png", True)

## GetRows

Wróći wobsah datoweho wobstatka w dwudimensionalnej matriksy, započinajo z prěnjej datowej sadźbu za aktualnej datowej sadźbu.

Po wuwjedźenju so kursor w lince pozicioněruje, kotraž je so jako poslednja čitała, za poslednjej datowej sadźbu w datowym wobstatku. W tutym padźe kajkosć EOF True wróći.

Tuta metoda da so wužiwać, zo by daty z datoweho wobstatka w blokach čitała, kotrychž wulkosć so pře argument maxrows definuje.

Wróćena matriks ma přeco dwě dimensiji, samo hdyž datowy wobstatk jednotliwu špaltu a jednotliwu datowu sadźbu wobsahuje.

### Syntaksa:

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

### Parametry:

header: Stajće tutón argument na True, zo by prěni zapisk w matriksy Array špaltowe hłowy wobsahował (standard = False).

maxrows: Definuje maksimalnu ličbu datowych sadźbow, kotrež so maja wróćić. Jeli ličba eksistowacych datowych sadźbow je mjeńša hač maxrows je wulkosć wróćeneje matriksy runja ličbje zbytnych datowych sadźbow w datowym wobstatku. Wostajće tutón argument prózdny abo stajće jón na nul, zo byšće wšě linki w datowym wobstatku wróćił (standard = 0).

### Přikład:

Slědowacy přikład datowy wobstatk w blokach z 100 linkami čita, doniž so cyły datowy wobstatk přečitany njeje.

##### W 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 Python

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

## GetValue

Wróći hódnotu podateho pola z aktualneje datoweje sadźby datoweho wobstatka.

Jeli podate polo je binarne, so jeho dołhosć wróći.

### Syntaksa:

svc.GetValue(fieldname: str): any

### Parametry:

fieldname: Mjeno pola, kotrež so ma wróćić, jako znamješkowy rjećazk, kotryž na wulkopisanje dźiwa.

### Přikład:

##### W Basic

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

##### W Python

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

## Insert

Zasadźuje nowu datowu sadźbu na kóncu datoweho wobstatka a inicializuje jeje pola z podatymi hódnotami.

Jeli primarny kluč datoweho wobstatka je awtomatiska hódnota, tuta metoda hódnotu primarneho kluča noweje datoweje sadźby wróći. Hewak metoda 0 wróći (hdyž je wuspěšna) abo -1 (hdyž je njewuspěšna).

Aktualizujomne pola z njepodatymi hódnotami so ze swojimi standardnymi hódnotami inicializuja.

Jeli podate polo je binarne, so jeho dołhosć wróći.

### Syntaksa:

svc.Insert(pvargs: any): int

### Parametry:

pvargs: Dictionary, kotryž pory pólnych mjenow a jich wotpowědowace hódnoty wobsahuje. Alternatiwnje da so runa ličba argumentow we wotměnje z pólnymi mjenami (jako String) a jich hódnotami podać.

### Přikład:

##### W Basic

Předstajće sej tabelu z mjenom „Kupcy“ z 4 polemi: „ID“ (BigInt, awtomatiska hódnota a primarny kluč), „Mjeno“ (VarChar), „Staroba“ (Integer), „Město“ (VarChar).

Slědowacy přikład nowu datowu sadźbu do tutoho datoweho wobstatka z pomocu Dictionary zasadźuje.

          oDataset = oDatabase.CreateDataset("Kupcy")
          oNewData = CreateScriptService("Dictionary")
          oNewData.Add("Mjeno", "Jan")
          oNewData.Add("Staroba", 50)
          oNewData.Add("Město", "Budyšin")
          lNewID = oDataset.Insert(oNewData)

Samsny wuslědk da so docpěć, hdyž so wšě pory polow a hódnoty jako argumenty přepodawaja:

          oDataset.Insert("Mjeno", "Jan", "Staroba", 50, "Město", "Budyšin")

##### W Python

          dataset = database.CreateDataset("Kupcy")
          new_data = {"Mjeno": "Jan", "Staroba": 30, "Město": "Budyšin"}
          new_id = dataset.Insert(new_data)

Slědowacy wuwołanja so w Python akceptuja:

          dataset.Insert("Mjeno", "Jan", "Staroba", 50, "Město", "Budyšin")
          dataset.Insert(Mjeno = "Jan", Staroba = 50, City = "Budyšin")

## MoveFirst / MoveLast

Pohibuje kursor datoweho wobstatka k prěnjej (z MoveFirst) abo k poslednjej (z MoveLast) datowej sadźbje.

Tuta metoda True wróća, hdyž je wuspěšna.

Zhašane datowe sadźby so přez tutu metodu ignoruja.

### Syntaksa:

svc.MoveFirst(): bool

svc.MoveLast(): bool

### Přikład:

##### W Basic

          oDataset.MoveFirst()

##### W Python

          dataset.MoveFirst()

## MoveNext / MovePrevious

Pohibuje kursor datoweho wobstatka doprědka (z MoveNext) abo dozady (z MovePrevious) wo datu ličbu datowych sadźbow.

Tuta metoda True wróća, hdyž je wuspěšna.

Zhašane datowe sadźby so přez tutu metodu ignoruja.

### Syntaksa:

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

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

### Parametry:

offset: Ličba datowych sadźbow, wo kotrež so ma kursor doprědka abo dozady pohibować. Tutón argument móže negatiwnu hódnotu měć (standard = 1).

### Přikład:

##### W Basic

          oDataset.MoveNext()
          oDataset.MoveNext(5)

##### W Python

          dataset.MoveNext()
          dataset.MoveNext(5)

## Reload

Začituje datowy wobstatk znowa z datoweje banki. Kajkosći Filter a OrderBy datej so definować, hdyž so tuta metoda wuwołuje.

Tuta metoda True wróća, hdyž je wuspěšna.

Nowe začitanje datoweho wobstatka je wužitne, hdyž su so datowe sadźby do datoweje banki zasadźili abo z datoweje banki zhašeli. Dźiwajće na to, zo metodźe createDataset a Reload podobne funkcije wuwjedźetej, Reload wšak samsnu klasowu instancu Dataset zaso wužiwa.

### Syntaksa:

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

### Parametry:

filter: Podawa wuměnjenje, kotremuž datowe sadźby dyrbja wotpowědować, zo bychu so do wróćeneho datoweho wobstatka zapřijeli. Tutón argument so jako SQL-přikat WHERE bjez klučoweho słowa „WHERE“ zwuraznja. Jeli tutón argument podaty njeje, so filter nałožuje, kotryž so w aktualnym datowym wobstatku wužiwa, hewak so aktualny filter z tutym argumentom wuměni.

orderby: Podawa porjad datoweho wobstatka jako SQL-přikaz ORDER BY bjez klučoweho słowa „ORDER BY“. Jeli tutón argument podaty njeje, so sortěrowanski porjad nałožuje, kotryž so w aktualnym wobstatku wužiwa, hewak so aktualny sortěrowanski porjad z tutym argumentom wuměni.

### Přikład:

##### W Basic

          oDataset.Reload()
          oDataset.Reload(Filter := "[Mjeno] = 'Jan'", OrderBy := "Staroba")

##### W Python

          dataset.Reload()
          dataset.Reload(Filter = "[Mjeno] = 'Jan'", OrderBy = "Staroba")

## Update

Aktualizuje hódnoty podatych polow w aktualnej datowej sadźbje.

Tuta metoda True wróća, hdyž je wuspěšna.

### Syntaksa:

svc.Update(pvargs: any): bool

### Parametry:

pvargs: Dictionary, kotryž pory pólnych mjenow a jich wotpowědowace hódnoty wobsahuje. Alternatiwnje da so runa ličba argumentow we wotměnje z pólnymi mjenami (jako String) a jich hódnotami podać.

### Přikład:

##### W Basic

Slědowacy přikład aktualnu datowu sadźbu z pomocu Dictionary aktualizuje.

          oNewValues = CreateScriptService("Dictionary")
          oNewValues.Add("Staroba", 51)
          oNewValues.Add("Město", "Kamjenc")
          oDataset.Update(oNewValues)

Samsny wuslědk da so docpěć, hdyž so wšě pory polow a hódnoty jako argumenty přepodawaja:

          oDataset.Update("Staroba", 51, "Město", "Kamjenc")

##### W Python

          new_values = {"Staroba": 51, "Město": "Kamjenc"}
          dataset.Update(new_values)

          dataset.Update("Staroba", 51, "Město", "Kamjenc")
          dataset.Update(Staroba = 51, Město = "Kamjenc")

Wšě rutiny Basic ScriptForge abo identifikatory, kotrež so z podsmužku „_“ započinaja, su za interne wužiwanje wuměnjene. Njejsu za to myslene, so w makrach Basic abo skriptach Python wužiwać.

Podobne temy

Słužba SFDatabases.Database

Prošu podpěrajće nas!