Vsebina

# 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 ali SQL.
UpdatableFields | Da | Array | Vrne polje Array z imeni polj nabora podatkov, ki jih je možno 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 ORDER BY.

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

          ' Uporabite prazen niz za odstranitev trenutnega filtra
          oNewDataset = oDataset.CreateDataset(Filter := "")
          ' Primeri pogosto uporabljenih pogojev
          oNewDataset = oDataset.CreateDataset(Filter = "[Ime] = 'Janez'")
          oNewDataset = oDataset.CreateDataset(Filter = "[Ime] LIKE 'A'")
          ' Trenutnemu filtru je možno dopisati dodatne pogoje
          oNewDataset = oDataset.CreateDataset(Filter := "(" & oDataset.Filter & ") AND [Ime] 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 definiciji zapisa 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 lahko prebere podatke iz nabora podatkov v kosih, katerih velikost določa argument maxrows.

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 iz 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 z navedenimi vrednostmi, ki jih je možno posodobiti, 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:

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

          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.

Podobne teme

Storitev SFDatabases.Database