Innhald

# SFDatabases.Dataset-tenesta

Database-tenesta er brukt for å representera tabulerte data laga av ein database. Med denne tenesta er det råd å:

- Navigere gjennom og få tilgang til dataa i eit datasett.

- Oppdatera, setja inn og sletta postar i datasettet.

Å oppdatera og setja inn postar går saktare med Dataset-metoden enne ved å bruka SQL-uttrykk. Skal du oppdatera eller setja inn mange postar, vert det difor rådd til å bruka SQL-metoden.

## Oppkall av tenester

Før du brukar tenesta Dataset må biblioteket ScriptForge vera lasta inn eller importert:

• Grunnleggjande makroar krev innlasting av biblioteket ScriptForge ved hjelp av denne setninga:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python-skript krev import frå scriptforge-modulen:
from scriptforge import CreateScriptService

Dataset-tenesta er kalla opp med CreateDataset-metoden, som igjen kan kallast opp frå anten ei Database-teneste eller frå eit anna Dataset.

##### I Basic

Eksempelet nedanfor lagar eit Dataset frå tabellen «Kundar» lagra i ei databasefil.

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

Når du lagar Dataset vert den gjeldande posten plassert framføre fen første posten.

Eksempelet nedanfor lagar eit Dataset ved å filtrera det originalen datasettet.

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

##### I Python

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

        new_dataset = dataset.CreateDataset(filter = "[By]='New York'")

## Eigenskapar

Namn | Skriveverna | Type | Beskriving
--- | --- | --- | ---
BOF | Nei | Boolean | Returnerer Sann vis den gjeldande posten er framføre den første posten i datasettet, elles vert Usann returnert. Set denne eigenskapen til Sann for å flytta markøren til byrjinga av datasettet. Set du eigenskapen til Usann, vert dette ignorert.
DefaultValues | Ja | Dictionary-tenesta | Returnerer ei ordliste med standardverdiane brukte i kvart felt i datasettet. Felta eller kolonnane i datasettet er nøklane i ordlista. felttypane i databasen vert konverterte til dei tilsvarande Basic/Python datatypene. Viss felttype er udefinert, er standardverdien Null viss feltet kan nullstillast eller kan vera Empty.
EOF | Nei | Boolean | Returnerer Sann vis den gjeldande posten er etter den siste posten i datasettet, elles vert Usann returnert. Set denne eigenskapen til Sann for å flytta markøren til slutten av datasettet. Set du eigenskapen til Usann, vert dette ignorert.
Fields | Ja | Array | Returnerer ein matrise med namna på alle felta i datasettet.
Filter | Ja | String | Returnerer filteret som vart brukt i tillegg til den eventuelle WHERE-setningsdelen i det første SQL-uttrykket. Denne eigenskapen vert uttrykt som ein WHERE-setningsdel utan nøkkelordet «WHERE».
OrderBy | Ja | String | Returnerer sorteringsnøkkelen som eventuelt skal bytast ut med ORDER BY i det opphavlege SQL-uttrykket. Eigenskapen vert presentert som ein ORDER BY utan «ORDER BY»-nøkkelorda.
ParentDatabase | Ja | Database-teneste | Returnerer førekomsten av Database som svarar til foreldredatabasen i det gjeldande datasettet.
RowCount | Ja | Long | Returnerer det nøyaktige talet på postar i datasettet. Merk at for å evaluera denne eigenskapen må heile datasettet gjennomgåast, noko som kan vera svært tidkrevjande ved store datasett.
RowNumber | Ja | Long | Returnerer nummeret til den gjeldande posten med start på 1. Returnerer 0 viss denne eigenskapen er ukjend.
Source | Ja | String | Returnerer kjelda til datasettet. Det kan anten vera eit tabellnamn, eit spørjingsnamn eller eit SQL-uttrykk.
SourceType | Ja | String | Returnerer kjelda til datasettet. Det kan vera ein av dei følgjande strengverdiane: TABLE, QUERY eller SQL.
UpdatableFields | Ja | Array | Returnerer ei matrise med namna på alle felta i datasettet.
Values | Ja | Array | Returnerer ei ordliste med para (feltnamn: verdi) for den gjeldande posten i datasettet.
XRowSet | Ja | UNO-objekt | Returnerer com.sun.star.sdb.RowSet UNO-objektet som representerer datasettet.

Liste over metodar i datasett-tenesta
CloseDataset CreateDataset Delete ExportValueToFile GetRows | GetValue Insert MoveFirst MoveLast | MoveNext MovePrevious Reload Update

## CloseDataset

Lukkar det gjeldande datasettet. Denne metoden returnerer Sann når han lukkast.

Det vert rådd til å lukka datasettet etter bruk for å frigje resursar.

### Syntaks:

svc.CloseDataset(): bool

### Eksempel:

##### I Basic

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

##### I Python

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

## CreateDataset

Returnerer ein førekomst av Dataset-tenesta frå eit eksisterande datasett ved å bruka det spesifiserte filteret og ORDER BY-uttrykk.

### Syntaks:

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

### Parametrar:

filter: Spesifiderer vilkåra som postane må oppfylla for å verta returnerte i datasettet. ette arguentet vert uttrykt som eit SQL WHERE-uttrykk utan nøkkelordet «WHERE». Viss dette argumentet ikkje er spesifisert, vert filteret i det gjeldande datasettet brukt., elles vert det gjeldande filteret byt ut med dette argumentet.

orderby: Spesifiserer rekkjefølgja på datasettet som eit SQL ORDER BY-uttrykk utan «ORDER BY»-nøkkelordet. Viss dette argumentet ikkje er spesifisert, vert rekkjefølgja i det gjeldande datasettet brukt, elles vert den gjeldande rekkjefølgja byt ut med dette argumentet.

### Eksempel:

##### I Basic

          ' Bruk ein tom streng for å fjerna det gjeldande filteret
          oNewDataset = oDataset.CreateDataset(Filter := "")
          ' Eksempel på vanlege filter
          oNewDataset = oDataset.CreateDataset(Filter := "[Name] = 'John'")
          oNewDataset = oDataset.CreateDataset(Filter := "[Name] LIKE 'A'")
          ' Det er mogleg å føya til ytterlegare vilkår til det gjeldande filteret
          oNewDataset = oDataset.CreateDataset(Filter := "(" & oDataset.Filter & ") AND [Name] LIKE 'A'")

##### I Python

          new_dataset = dataset.CreateDataset(filter = "")
          new_dataset = dataset.CreateDataset(filter = "[Namn] = 'John'")
          new_dataset = dataset.CreateDataset(filter = "[Name] LIKE 'A'")
          new_dataset = dataset.CreateDataset(filter = f"({dataset.Filter}) AND [Name] LIKE 'A'")

## Delete

Slettar den gjeldande posten frå datasettet. Denne metoden returnerer Sann når han lukkast.

Etter denne operasjonen vert markøren plassert på posten like etter den sletta posten. Viss den sletta posten er den siste i datasettet, vert markøren plassert etter denne og eigenskapen EOF returnerer Sann.

### Syntaks:

svc.Delete(): bool

### Eksempel:

##### I Basic

          oDataset.Delete()

##### I Python

          dataset.Delete()

## ExportValueToFile

Eksporterer verdien av eit binært felt i den gjeldande posten til ei spesifisert fil.

Viss det spesifiserte feltet ikkje er binært eller det ikkje inneheld data, vert utdatafila ikkje oppretta.

### Syntaks:

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

### Parametrar:

feltnamn: Namnet på binærfeltet som skal eksporterast som ein streng som skil mellom store og små bokstavar.

filnamn: Den fullstendige stien til fila som skal opprettast slik det er definert i eigenskapen FileSystem.FileNaming.

overwrite: Set dette argumentet til Sann slik at målfila kan overskrivast (standard = Usann).

### Eksempel:

I eksempelet nedanfor inneheld datasettet ein post kalla «Bilete» som skal eksporterast til ei biletfil.

##### I Basic

          oDataset.ExportValueToFile("Bilete", "C:\Biletet_mitt.png", True)

##### I Python

          dataset.ExportValueToFile("Bilete",r"C:\Biletet_mitt.png", True)

## GetRows

Returnerer innheldet i datasettet i ei todimensjonal matrise som byrjar frå den første posten etter den gjeldande posten.

Etter utføringa vert markøren sett på den rada som sist vart lese eller etter den siste posten i datasettet. I det siste tilfelle returnerer eigenskapen EOF Sann.

Denne metoden kan brukast til å lesa data frå datasettet i bitar der storleiken er definert av argumentet maxrows.

Den returnerte matrisen vil alltid ha to dimensjonar, sjølv om datasettet inneheld éin enkelt kolonne eller berre éin post.

### Syntaks:

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

### Parametrar:

header: Set dette argumentet til Sann for å få den første oppføringa i Array til å innehalda kolonneoverskriftene (Standard = Usann).

maxrows: Definer det høgste talet på postar som skal returnerast. Viss talet på eksisterande postar er mindre enn maxrows, vert storleiken på den returnerte matrisa den same som talet på postar som er igjen i datasettet. Lat dette argumentet vera tomt, eller set det til null for å returnera alle radene i datasettet (Standard = 0)

### Eksempel:

Eksempelet nedanfor les eit datasett i bitar på 100 rader til heile datasettet er lese.

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

##### I Python

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

## GetValue

Returnerer verdien av det spesifiserte feltet i den gjeldande posten i datasettet.

Viss det spesifiserte feltet er binært, vert lengda returnert.

### Syntaks:

svc.GetValue(fieldname: str): any

### Parametrar:

feltnamn: Namnet på feltet som skal returnerast som ein streng som skil mellom store og små bokstavar.

### Eksempel:

##### I Basic

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

##### I Python

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

## Insert

Set inn ein ny post ved slutten av datasettet og set opp felta med dei gjevne verdiane.

Viss primærnøkkelen for datasettet er ein automatisk verdi, vil denne metoden returnera verdien av primærnøkkelen for den nye posten. Metoden returnerer 0 (når han lukkast) eller -1 (når han ikkje lukkast).

Oppdaterbare felt med uspesifiserte verdiar vert sette opp med standardverdiane.

Viss det spesifiserte feltet er binært, vert lengda returnert.

### Syntaks:

svc.Insert(pvargs: any): int

### Parametrar:

pvargs: Ei ordbok som inneheld par med feltnamn og deira respektive verdiar. Alternativt kan eit partall av argument spesifiserast med vekslande feltnamn (som ein String) og verdiane deira.

### Eksempel:

##### I Basic

Tenk på ein tabell med namnet «Kundar» med fire felt: «ID» (BigInt, autoverdi og primærnøkkel), «Namn» (VarChar), «Alder» (Integer), «By» (VarChar).

Eksempelet nedanfor set inn ein ny post i datasettet ved hjelp av ei ordbok.

          oDataset = oDatabase.CreateDataset("Kundar")
          oNewData = CreateScriptService("Dictionary")
          oNewData.Add("Namn", "John")
          oNewData.Add("Alder", 50)
          oNewData.Add("By", "Chicago")
          lNewID = oDataset.Insert(oNewData)

Du kan få det same resultatet ved å senda alle feltpara og verdiane som argument.

          oDataset.Insert("Namn", "John", "Alder", 50, "By", "Chicago")

##### I Python

          dataset = database.CreateDataset("Kundar")
          new_data = {"Namn": "John", "Agler": 30, "By": "Chicago"}
          new_id = dataset.Insert(new_data)

Oppkalla nedanfor vert godtekne i Python:

          dataset.Insert("Namn", "John", "Alder", 50, "By", "Chicago")
          dataset.Insert(Namn = "John", Alder = 50, By = "Chicago")

## MoveFirst / MoveLast

Flyttar datasetmarkøren til den første (med MoveFirst) eller til den siste (med MoveLast) posten.

Denne metoden returnerer Sann når han lukkast.

Sletta postar vert ignorerte med denne metoden.

### Syntaks:

svc.MoveFirst(): bool

svc.MoveLast(): bool

### Eksempel:

##### I Basic

          oDataset.MoveFirst()

##### I Python

          dataset.MoveFirst()

## MoveNext / MovePrevious

Flytt datasettmarkøren framover (med MoveNext) eller bakover (med MovePrevious) eit gjeve tal på postar.

Denne metoden returnerer Sann viss han lukkast.

Sletta postar vert ignorerte med denne metoden.

### Syntaks:

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

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

### Parametrar:

offset: Kor mange postar markøren skal flyttast framover eller bakover. Dette argumentet kan vera negativt (standard = 1).

### Eksempel:

##### I Basic

          oDataset.MoveNext()
          oDataset.MoveNext(5)

##### I Python

          dataset.MoveNext()
          dataset.MoveNext(5)

## Reload

Lastar datasettet på nytt frå databasen. Eigenskapane Filter og OrderBy kan definerast når denne metoden vert kalla opp.

Denne metoden returnerer Sann når han lukkast.

Det vil vera nyttig å lasta inn datasettet på nytt når det er sett inn eller sletta postar i databasen. Merk at metodane CreateDataset og Reload utfører liknande funksjonar, men Reload brukar den same førekomsten av Dataset-klassen.

### Syntaks:

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

### Parametrar:

filter: Spesifiderer vilkåra som postane må oppfylla for å verta returnerte i datasettet. ette arguentet vert uttrykt som eit SQL WHERE-uttrykk utan nøkkelordet «WHERE». Viss dette argumentet ikkje er spesifisert, vert filteret i det gjeldande datasettet brukt., elles vert det gjeldande filteret byt ut med dette argumentet.

orderby: Spesifiserer rekkjefølgja på datasettet som eit SQL ORDER BY-uttrykk utan «ORDER BY»-nøkkelordet. Viss dette argumentet ikkje er spesifisert, vert rekkjefølgja i det gjeldande datasettet brukt, elles vert den gjeldande rekkjefølgja byt ut med dette argumentet.

### Eksempel:

##### I Basic

          oDataset.Reload()
          oDataset.Reload(Filter := "[Namn] = 'John'", OrderBy := "Alder")

##### I Python

          dataset.Reload()
          dataset.Reload(Filter = "[Namn] = 'John'", OrderBy = "Alder")

## Update

Oppdaterer verdiane i dei spesifiserte felta i den gjeldande posten.

Denne metoden returnerer Sann når han lukkast.

### Syntaks:

svc.Update(pvargs: any): bool

### Parametrar:

pvargs: Ei ordbok som inneheld par med feltnamn og deira respektive verdiar. Alternativt kan eit partall av argument spesifiserast med vekslande feltnamn (som ein String) og verdiane deira.

### Eksempel:

##### I Basic

Eksempelet nedanfor oppdaterer den gjeldande poste ved å bruka Dictionary.

          oNewValues = CreateScriptService("Dictionary")
          oNewValues.Add("Alder", 51)
          oNewValues.Add("By", "New York")
          oDataset.Update(oNewValues)

Du kan få det same resultatet ved å senda alle feltpara og verdiane som argument.

          oDataset.Update("Alder", 51, "By", "New York")

##### I Python

          new_values = {"Alder": 51, "By": "New York"}
          dataset.Update(new_values)

          dataset.Update("Alder", 51, "By", "New York")
          dataset.Update(Alder = 51, By = "New York")

Alle ScriptForge Basic-rutinane og -identifikatorane som vert innleidde med understrek «_» er reserverte for internt bruk. Dei er ikkje meint brukte i Basic-makroar.

Liknande emne

Tenesta SFDatabases.Database