Storitev SFDatabases.Dataset

Storitev Dataset se uporablja za predstavljanje tabelaričnih podatkov, ki jih izdela zbirka podatkov. S to storitvijo je možno:

dostop in krmarjenje po podatkih v naboru podatkov;
posodabljanje, vstavljanje in odstranjevanje zapisov v naboru podatkov.

Posodabljanje in vstavljanje zapisov s storitvijo Dataset je počasnejše od uporabe ukazov SQL. Če posodabljate ali vstavljate velike količine zapisov, priporočamo, da uporabljate ukaze SQL namesto metod iz te storitve.

Priklic storitve

Pred uporabo storitve Dataset je potrebno naložiti ali uvoziti knjižnico ScriptForge:

• Za makre Basic mora biti naložena knjižnica ScriptForge z naslednjim ukazom:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Za skripte Python mora biti opravljen uvoz iz modula scriptforge:
from scriptforge import CreateScriptService

Storitev Dataset prikličete z uporabo metode CreateDataset, ki jo lahko kličete iz instance storitve Database ali iz druge instance Dataset.

V Basicu

Naslednji primer ustvari Dataset iz tabele »Stranke«, shranjene v datoteki zbirke podatkov.


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

Ob nastanku nabora podatkov Dataset se trenutni zapis nahaja pred prvim zapisom.

Spodnji primer ustvari instanco storitve Dataset s filtriranjem izvirnega nabora podatkov.


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

V Pythonu


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


    new_dataset = dataset.CreateDataset(filter = "[Kraj]='Ljubljana'")

Lastnosti

Ime	Samo za branje	Vrsta	Opis
BOF	Ne	Boolean	Vrne True, če je trenutni položaj zapisa pred prvim zapisom v množici zapisov, sicer vrne False. Nastavite to lastnost na True, da pomaknete kazalko na začetek nabora podatkov oz. množice zapisov. Nastavljanje te lastnosti na False je prezrto.
DefaultValues	Da	Storitev Dictionary	Vrne Dictionary s privzetimi vrednostmi, uporabljenimi za vsako polje v naboru podatkov. Polja ali stolpci v naboru podatkov so ključi v slovarju. Vrste polj zbirke podatkov se pretvorijo v ustrezne podatkovne vrste Basic/Python. Če je vrsta polja nedefinirana, je privzeta vrednost Null, če je polje mogoče izničiti, ali Empty.
EOF	Ne	Boolean	Vrne True, če je trenutni položaj zapisa po zadnjem zapisu v množici zapisov, sicer vrne False. Nastavite to lastnost na True, da pomaknete kazalko na konec nabora podatkov. Nastavljanje te lastnosti na False je prezrto.
Fields	Da	Array	Vrne polje Array z imeni vseh polj v naboru podatkov.
Filter	Da	String	Vrne uveljavljen filter poleg morebitnih stavkov WHERE v začetnem ukazu SQL. Ta lastnost je izražena kot ukaz WHERE brez ključne besede »WHERE«.
OrderBy	Da	String	Vrne ukaz razvrščanja, ki zamenja morebitni stavek ORDER BY, prisoten v začetnem ukazu SQL. Ta lastnost je izražena kot ukaz ORDER BY brez ključne besede »ORDER BY«.
ParentDatabase	Da	Storitev Database	Vrne instanco storitve Database, ki ustreza nadrejeni zbirki podatkov trenutnega nabora podatkov.
RowCount	Da	Long	Vrne natanko število zapisov v naboru podatkov. Upoštevajte, da ovrednotenje te lastnosti implicira brskanje po celem naboru podatkov, kar lahko predstavlja visok strošek glede na velikost nabora podatkov.
RowNumber	Da	Long	Vrne številko trenutnega zapisa, začenši z 1. Vrne 0, če ta lastnosti ni znana.
Source	Da	String	Vrne vir nabora podatkov. To je lahko ime tabele, ime poizvedbe ali izjava SQL.
SourceType	Da	String	Vrne vir nabora podatkov. To je lahko niz z eno od naslednjih vrednosti: TABLE, QUERY in SQL.
UpdatableFields	Da	Array	Vrne polje Array z imeni polj nabora podatkov, ki jih je moč posodobiti.
Values	Da	Array	Vrne Dictionary s pari (ime polja: vrednost) trenutnega zapisa v naboru podatkov.
XRowSet	Da	Predmet UNO	Vrne predmet UNO com.sun.star.sdb.RowSet, ki predstavlja nabor podatkov.

Seznam metod v storitvi Dataset
CloseDataset CreateDataset Delete ExportValueToFile GetRows	GetValue Insert MoveFirst MoveLast	MoveNext MovePrevious Reload Update

CloseDataset

Zapre trenutni nabor podatkov. Metoda vrne True, če uspe.

Priporočamo, da po uporabi nabora podatkov le tega zaprete, da sprostite vire.

Skladnja:

svc.CloseDataset(): bool

Primer:

V Basicu


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

V Pythonu


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

CreateDataset

Vrne instanco storitve Dataset iz obstoječega nabora podatkov z uveljavljanjem določenega filtra in ukazov za razvrščanje.

Skladnja:

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

Parametri:

filter: določa pogoj, ki ga morajo izpolnjevati zapisi, da so vključeni v vrnjeni nabor podatkov. Ta argument je izražen kot ukaz SQL WHERE brez ključne besede »WHERE«. Če ta argument ni naveden, potem se uveljavi filter, uporabljen v trenutnem naboru podatkov, sicer se trenutni filter nadomesti s tem argumentom.

orderby: določa razvrstitev nabora podatkov kot ukaz SQL ORDER BY brez ključne besede »ORDER BY«. Če ta argument ni naveden, potem se uveljavi zaporedje razvrščanja kot v trenutnem naboru podatkov, sicer trenutno zaporedje razvrščanja nadomesti ta argument.

Primer:

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 = "[Ime] = 'Janez'")
      new_dataset = dataset.CreateDataset(filter = "[Ime] LIKE 'A'")
      new_dataset = dataset.CreateDataset(filter = f"({dataset.Filter}) AND [Ime] LIKE 'A'")

Delete

Izbriše trenutni zapis iz nabora podatkov. Ta metoda vrne True, če uspe.

Po tej operaciji je kazalec postavljen na zapis neposredno za izbrisanim zapisom. Če je izbrisani zapis zadnji v naboru podatkov, potem se kazalec postavi za njim in lastnost EOF vrne True.

Skladnja:

svc.Delete(): bool

Primer:

V Basicu


      oDataset.Delete()

V Pythonu


      dataset.Delete()

ExportValueToFile

Izvozi vrednost dvojiškega polja trenutnega zapisa v navedeno datoteko.

Če navedeno polje ni dvojiško ali ne vsebuje podatkov, izhodna datoteka ne bo ustvarjena.

Skladnja:

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

Parametri:

fieldname: ime dvojiškega polja, ki bo izvoženo; niz, ki razlikuje med velikimi in malimi črkami.

filename: polna pot do datoteke, ki jo želite ustvariti; slediti mora zapisu v lastnosti FileSystem.FileNaming.

overwrite: nastavite ta argument na True, da je ciljno datoteko možno prepisati (privzeta vrednost je False).

Primer:

V spodnjem primeru nabor podatkov vsebuje polje »Slika«, ki naj se izvozi v slikovno datoteko.

V Basicu


      oDataset.ExportValueToFile("Slika", "C:\moja_slika.png", True)

V Pythonu


      dataset.ExportValueToFile("Slika", r"C:\moja_slika.png", True)

GetRows

Vrne vsebino nabora podatkov v dvodimenzionalnem polju, začenši s prvim zapisom po trenutnem zapisu.

Po izvedbi se kazalec nahaja pri vrstici, ki je bila nazadnje prebrana ali za zadnjim zapisom v naboru podatkov, v tem primeru lastnost EOF vrne True.

Ta metoda pošlje vsebino dokumenta privzetemu tiskalniku ali tiskalniku, ki ga določa metoda SetPrinter.

Vrnjeno polje bo imelo vedno dve dimenziji, tudi če nabor podatkov vsebuje en sam stolpec in en sam zapis.

Skladnja:

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

Parametri:

header: nastavite ta argument na True, da bo prvi vnos v polju Array vseboval glave stolpcev (privzeta vrednost je False).

maxrows: določite največje število zapisov, ki bodo vrnjeni. Če je število obstoječih zapisov manjše kot maxrows, bo vrnjeno polje imelo samo obstoječe zapise. Pustite ta argument prazen ali ga nastavite na nič, da vrne vse vrstice v naboru podatkov (privzeta vrednost je 0).

Primer:

Naslednji primer prebere nabor podatkov v kosih po 100 vrstic, dokler ni prebran celoten nabor podatkov.

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

Vrne vrednost navedenega polja od trenutnega zapisa nabora podatkov.

Če navedeno polje ni dvojiško, vrne njegovo dolžino.

Skladnja:

svc.GetValue(fieldname: str): any

Parametri:

fieldname: ime polja, ki bo vrnjeno, kot niz; razlikuje med velikimi in malimi črkami.

Primer:

V Basicu


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

V Pythonu


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

Insert

Vstavi nov zapis na konec nabora podatkov in inicializira njegova polja z navedenimi vrednostmi.

Če je primarni ključ nabora podatkov samodejna vrednost, ta metoda vrne vrednost primarnega ključa novega zapisa. Sicer metoda vrne 0 (če je uspešna) ali -1 (če ni uspešna).

Polja, ki jih je moč posodobiti z nenavedenimi vrednostmi, se inicializirajo s svojimi privzetimi vrednostmi.

Če navedeno polje ni dvojiško, vrne njegovo dolžino.

Skladnja:

svc.Insert(pvargs: any): int

Parametri:

pvargs: Dictionary, ki vsebuje pare imen polj in njihovih vrednosti. Namesto tega lahko navedete sodo število argumentov, kjer se izmenjujejo imena polj (kot nizi String) in njihove vrednosti.

Primer:

V Basicu

Predstavljajte si tabelo »Stranke« s 4 polji: »ID« (BigInt, samodejna vrednost in primarni ključ), »Ime« (VarChar), »Starost« (Integer), »Kraj« (VarChar).

Spodnji primer vstavi nov zapis v ta nabor podatkov z uporabo Dictionary.


      oDataset = oDatabase.CreateDataset("Stranke")
      oNewData = CreateScriptService("Dictionary")
      oNewData.Add("Ime", "Janez")
      oNewData.Add("Starost", 50)
      oNewData.Add("Kraj", "Celje")
      lNewID = oDataset.Insert(oNewData)

Enak rezultat lahko dosežemo s podajanjem vseh parov polj in vrednosti kot argumentov:


      oDataset.Insert("Ime", "Janez", "Starost", 50, "Kraj", "Celje")

V Pythonu


      dataset = database.CreateDataset("Stranke")
      new_data = {"Ime": "Janez", "Starost": 30, "Kraj": "Celje"}
      new_id = dataset.Insert(new_data)

Naslednji klici so sprejeti v Pythonu:


      dataset.Insert("Ime", "Janez", "Starost", 50, "Kraj", "Celje")
      dataset.Insert(Ime = "Janez", Starost = 50, Kraj = "Celje")

MoveFirst / MoveLast

Premakne kazalec nabora podatkov na prvi (z MoveFirst) ali zadnji (z MoveLast) zapis.

Ta metoda vrne True, če uspe.

Ta metoda prezre izbrisane zapise.

Skladnja:

svc.MoveFirst(): bool

svc.MoveLast(): bool

Primer:

V Basicu


      oDataset.MoveFirst()

V Pythonu


      dataset.MoveFirst()

MoveNext / MovePrevious

Premakne kazalec nabora podatkov naprej (z MoveNext) ali nazaj (z MovePrevious) za dano število zapisov.

Ta metoda vrne True, če uspe.

Ta metoda prezre izbrisane zapise.

Skladnja:

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

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

Parametri:

offset: število zapisov, za kolikor se želite pomakniti naprej ali nazaj. Argument ima lahko negativno vrednost (privzeto = 1).

Primer:

V Basicu


      oDataset.MoveNext()
      oDataset.MoveNext(5)

V Pythonu


      dataset.MoveNext()
      dataset.MoveNext(5)

Reload

Ponovno naloži nabor podatkov iz zbirke podatkov. Lastnosti Filter in OrderBy sta lahko definirani pri klicu te metode.

Ta metoda vrne True, če uspe.

Ponovno nalaganje nabora podatkov je uporabno, ko so bili v zbirko podatkov vstavljeni ali izbrisani zapisi. Upoštevajte, da metodi CreateDataset in Reload izvajata podobni funkciji, medtem ko Reload ponovno uporabi iste instance razreda Dataset.

Skladnja:

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

Parametri:

Primer:

V Basicu


      oDataset.Reload()
      oDataset.Reload(Filter := "[Ime] = 'Janez'", OrderBy := "Starost")

V Pythonu


      dataset.Reload()
      dataset.Reload(Filter = "[Ime] = 'Janez'", OrderBy = "Starost")

Update

Posodobite vrednosti navedenih polj v trenutnem zapisu.

Ta metoda vrne True, če uspe.

Skladnja:

svc.Update(pvargs: any): bool

Parametri:

pvargs: Dictionary, ki vsebuje pare imen polj in njihovih vrednosti. Namesto tega lahko navedete sodo število argumentov, kjer se izmenjujejo imena polj (kot nizi String) in njihove vrednosti.

Primer:

V Basicu

Spodnji primer posodobi trenutni zapis z uporabo Dictionary.


      oNewValues = CreateScriptService("Dictionary")
      oNewValues.Add("Starost", 51)
      oNewValues.Add("Kraj", "Ljubljana")
      oDataset.Update(oNewValues)

Enak rezultat lahko dosežemo s podajanjem vseh parov polj in vrednosti kot argumentov:


      oDataset.Update("Starost", 51, "Kraj", "Ljubljana")

V Pythonu


      new_values = {"Starost": 51, "Kraj": "Ljubljana"}
      dataset.Update(new_values)


      dataset.Update("Starost", 51, "Kraj", "Ljubljana")
      dataset.Update(Starost = 51, Kraj = "Ljubljana")

Vsi podprogrami ali identifikatorji ScriptForge Basic s predpono podčrtaja (»_«) so rezervirani za interno uporabo. Uporabi v makrih Basic ali skriptih Python niso namenjeni.

Storitev SFDatabases.Database