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

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

    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

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

svc.CloseDataset(): bool

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

      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.

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

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.

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

      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.

svc.Delete(): bool

      oDataset.Delete()
    

      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.

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

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

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

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

      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.

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

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

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

      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

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

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

svc.GetValue(fieldname: str): any

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

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

      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.

svc.Insert(pvargs: any): int

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

      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.

svc.MoveFirst(): bool

svc.MoveLast(): bool

      oDataset.MoveFirst()
    

      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.

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

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

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

      oDataset.MoveNext()
      oDataset.MoveNext(5)
    

      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.

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

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.

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

      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.

svc.Update(pvargs: any): bool

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

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

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