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:

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.

Tenesta SFDatabases.Database