SFDatabaser.Datasett-tjeneste

Tjenesten Datasett brukes til å representere tabelldata produsert av en database. Med denne tjenesten er det mulig å:

Naviger gjennom og få tilgang til dataene i et datasett.
Oppdater, sett inn og fjern poster i et datasett.

Oppdatering og innsetting av poster ved hjelp av Dataset-tjenesten er tregere enn å bruke SQL-setninger. Når du oppdaterer eller setter inn store mengder poster, anbefales det å bruke SQL-setninger i stedet for å bruke metodene i denne tjenesten.

Tjenesteaktivering

Før du bruker Dataset-tjenesten, må ScriptForge-biblioteket lastes eller importeres:

• Grunnleggende makroer krever å laste ScriptForge-biblioteket ved hjelp av følgende setning:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python-skript krever import fra scriptforge-modulen:
fra scriptforge import CreateScriptService

Dataset-tjenesten påkalles ved hjelp av CreateDataset-metoden, som kan kalles enten fra en Database-tjenesteforekomst eller fra et annet Dataset bokstavelig> forekomst.

I Basic

Følgende eksempel oppretter et Datasett fra tabellen "Kunder" lagret i en databasefil.


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

Ved opprettelsen av Datasettet, blir gjeldende post plassert før den første posten.

Eksemplet nedenfor oppretter en Datasett-forekomst ved å filtrere det opprinnelige datasettet.


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

I Python


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


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

Egenskaper

Navn	Skrivebeskyttet	Type	Beskrivelse
BOF	Nei	Boolean	Returnerer Sann hvis gjeldende postposisjon er før den første posten i datasettet, ellers returnerer Usann. Sett denne egenskapen til Sann for å flytte markøren til begynnelsen av datasettet. Å sette denne egenskapen til Usann ignoreres.
DefaultValues	Ja	Ordbok tjeneste	Returnerer en Ordbok med standardverdiene som brukes for hvert felt i datasettet. Feltene eller kolonnene i datasettet er nøklene i ordboken. Databasefelttypene konverteres til deres tilsvarende Basic/Python-datatyper. Når felttypen er udefinert, er standardverdien Null hvis feltet er nullbart eller Tom.
EOF	Nei	Boolean	Returnerer Sann hvis gjeldende postposisjon er etter den siste posten i datasettet, ellers returnerer Usann. Sett denne egenskapen til Sann for å flytte markøren til slutten av datasettet. Å sette denne egenskapen til Usann ignoreres.
Fields	Ja	Array	Returnerer en Matrise som inneholder navnene på alle feltene i datasettet.
Filter	Ja	String	Returnerer filteret brukt i tillegg til den eventuelle WHERE-setningen(e) i den innledende SQL-setningen. Denne egenskapen uttrykkes som en WHERE-klausul uten nøkkelordet "WHERE".
OrderBy	Ja	String	Returnerer bestillingsleddet som erstatter den eventuelle ORDER BY-leddet som finnes i den innledende SQL-setningen. Denne egenskapen er uttrykt som en ORDER BY-klausul uten "ORDER BY"-nøkkelordene.
ParentDatabase	Ja	Database tjeneste	Returnerer Database-forekomsten som tilsvarer den overordnede databasen til gjeldende datasett.
RowCount	Ja	Long	Returnerer det nøyaktige antallet poster i datasettet. Merk at evalueringen av denne egenskapen innebærer å bla gjennom hele datasettet, noe som kan være kostbart avhengig av datasettstørrelsen.
RowNumber	Ja	Long	Returnerer nummeret til gjeldende post som starter på 1. Returnerer 0 hvis denne egenskapen er ukjent.
Source	Ja	String	Returnerer kilden til datasettet. Det kan enten være et tabellnavn, et spørringsnavn eller en SQL-setning.
SourceType	Ja	String	Returnerer kilden til datasettet. Det kan være en av følgende strengverdier: TABLE, QUERY eller SQL.
UpdatableFields	Ja	Array	Returnerer en Matrise som inneholder navnene på feltene i datasettet som kan oppdateres.
Values	Ja	Array	Returnerer en Ordbok som inneholder parene (feltnavn: verdi) til gjeldende post i datasettet.
XRowSet	Ja	UNO objekt	Returnerer com.sun.star.sdb.RowSet UNO-objektet som representerer datasettet.

Liste over metoder i datasetttjenesten
CloseDataset CreateDataset Delete ExportValueToFile GetRows	GetValue Insert MoveFirst MoveLast	MoveNext MovePrevious Reload Update

CloseDataset

Lukker gjeldende datasett. Denne metoden returnerer True når den er vellykket.

Det anbefales å lukke datasettet etter bruk for å frigjøre ressurser.

Syntaks:

svc.CloseDataset(): bool

Eksempel:

I Basic


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

I Python


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

CreateDataset

Returnerer en Datasett-tjenesteforekomst fra et eksisterende datasettet ved å bruke det angitte filteret og sorteringsrekkefølge.

Syntaks:

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

Parametre:

filter: Angir betingelsen som poster må samsvare med for å bli inkludert i det returnerte datasettet. Dette argumentet er uttrykt som en SQL WHERE-setning uten nøkkelordet "WHERE". Hvis dette argumentet ikke er spesifisert, brukes filteret som brukes i gjeldende datasett, ellers erstattes det gjeldende filteret med dette argumentet.

ordreby: Spesifiserer rekkefølgen av datasettet som en SQL ORDER BY-setning uten nøkkelordet "ORDER BY". Hvis dette argumentet ikke er spesifisert, brukes sorteringsrekkefølgen som brukes i gjeldende datasett, ellers erstattes gjeldende sorteringsrekkefølge med dette argumentet.

Eksempel:

I Basic


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

I Python


      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

Sletter gjeldende post fra datasettet. Denne metoden returnerer Sann når den er vellykket.

Etter denne operasjonen plasseres markøren på posten umiddelbart etter den slettede posten. Hvis den slettede posten er den siste i datasettet, plasseres markøren etter den, og egenskapen EOF returnerer Sann.

Syntaks:

svc.Delete(): bool

Eksempel:

I Basic


      oDataset.Delete()

I Python


      dataset.Delete()

ExportValueToFile

Eksporterer verdien av et binært felt for gjeldende post til den angitte filen.

Hvis det angitte feltet ikke er binært, eller hvis det ikke inneholder noen data, opprettes ikke utdatafilen.

Syntaks:

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

Parametre:

feltnavn: Navnet på det binære feltet som skal eksporteres, som en streng som skiller mellom store og små bokstaver.

filnavn: Den fullstendige stien til filen som skal opprettes ved hjelp av notasjonen definert i egenskapen Filsystem.Filnavn.

overskriv: Sett dette argumentet til Sann for å tillate at målfilen overskrives (Standard = Usann).

Eksempel:

I eksemplet nedenfor inneholder datasettet et felt kalt "Bilde" som skal eksporteres til en bildefil.

I Basic


      oDataset.ExportValueToFile("Picture", "C:\my_image.png", Sann)

I Python


      dataset.ExportValueToFile("Picture", r"C:\my_image.png", Sann)

GetRows

Returnerer innholdet i datasettet i en 2-dimensjonal matrise, med start fra den første posten etter gjeldende post.

Etter utførelse plasseres markøren på raden som sist ble lest eller etter den siste posten i datasettet, i så fall returnerer egenskapen EOF Sann.

Denne metoden kan brukes til å lese data fra datasettet i biter, hvis størrelse er definert av maxrows-argumentet.

Den returnerte matrisen vil alltid ha to dimensjoner, selv om datasettet inneholder en enkelt kolonne og en enkelt post.

Syntaks:

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

Parametre:

Overskrift: Sett dette argumentet til Sann for å få den første oppføringen i Matrise til å inneholde kolonneoverskriftene (Standard = Usann).

maxrows: Definerer maksimalt antall poster som skal returneres. Hvis antallet eksisterende poster er mindre enn maxrows, vil størrelsen på den returnerte matrisen være lik antall gjenværende poster i datasettet. La dette argumentet stå tomt eller sett det til null for å returnere alle rader i datasettet (standard = 0)

Eksempel:

Følgende eksempel leser et datasett i biter på 100 rader til alt datasettet er lest.

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 til det angitte feltet fra gjeldende post for datasettet.

Hvis det angitte feltet er binært, returneres lengden.

Syntaks:

svc.GetValue(fieldname: str): any

Parametre:

feltnavn: Navnet på feltet som skal returneres, som en streng som skiller mellom store og små bokstaver.

Eksempel:

I Basic


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

I Python


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

Insert

Setter inn en ny post på slutten av datasettet og initialiserer feltene med de angitte verdiene.

Hvis primærnøkkelen til datasettet er en automatisk verdi, returnerer denne metoden primærnøkkelverdien til den nye posten. Ellers vil metoden returnere 0 (når vellykket) eller -1 (når ikke vellykket).

Oppdaterbare felt med uspesifiserte verdier initialiseres med standardverdiene.

Hvis det angitte feltet er binært, returneres lengden.

Syntaks:

svc.Insert(pvargs: any): int

Parametre:

pvargs: En Ordbok som inneholder par med feltnavn og deres respektive verdier. Alternativt kan et partall av argumenter spesifiseres vekslende feltnavn (som en streng) og deres verdier.

Eksempel:

I Basic

Tenk på en tabell kalt "Kunder" med 4 felt: "ID" (BigInt, automatisk verdi og primærnøkkel), "Navn" (VarChar), "Alder" (Heltall), "By" (VarChar).

Eksemplet nedenfor setter inn en ny post i dette datasettet ved hjelp av en Ordbok.


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

Det samme resultatet kan oppnås ved å sende alle par av felt og verdier som argumenter:


      oDataset.Insert("Name", "John", "Age", 50, "City", "Chicago")

I Python


      dataset = database.CreateDataset("Kunder")
      new_data = {"Name": "John", "Age": 30, "City": "Chicago"}
      new_id = dataset.Insert(new_data)

Følgende anrop godtas i Python:


      dataset.Insert("Name", "John", "Age", 50, "City", "Chicago")
      dataset.Insert(Name = "John", Age = 50, City = "Chicago")

MoveFirst / MoveLast

Flytter datasettmarkøren til den første (med MoveFirst) eller til den siste (med MoveLast) posten.

Denne metoden returnerer Sann når den er vellykket.

Slettede poster ignoreres av denne metoden.

Syntaks:

svc.MoveFirst(): bool

svc.MoveLast(): bool

Eksempel:

I Basic


      oDataset.MoveFirst()

I Python


      dataset.MoveFirst()

MoveNext / MovePrevious

Flytter datasettmarkøren fremover (med MoveNext) eller bakover (med MovePrevious) med et gitt antall poster.

Denne metoden returnerer Sann når den er vellykket.

Slettede poster ignoreres av denne metoden.

Syntaks:

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

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

Parametre:

offset: Antall poster som markøren skal flyttes forover eller bakover. Dette argumentet kan være en negativ verdi (Standard = 1).

Eksempel:

I Basic


      oDataset.MoveNext()
      oDataset.MoveNext(5)

I Python


      dataset.MoveNext()
      dataset.MoveNext(5)

Reload

Laster datasettet på nytt fra databasen. Egenskapene Filter og OrderBy kan defineres når denne metoden kalles.

Denne metoden returnerer Sann når den er vellykket.

Å laste datasettet på nytt er nyttig når poster har blitt satt inn i eller slettet fra databasen. Merk at metodene CreateDataset og Reload utfører lignende funksjoner, men Reload gjenbruker den samme Dataset klasseforekomsten.

Syntaks:

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

Parametre:

Eksempel:

I Basic


      oDataset.Reload()
      oDataset.Reload(Filter := "[Name] = 'John'", OrderBy := "Age")

I Python


      dataset.Reload()
      dataset.Reload(Filter = "[Name] = 'John'", OrderBy = "Age")

Update

Oppdater verdiene til de angitte feltene i gjeldende post.

Denne metoden returnerer Sann når den er vellykket.

Syntaks:

svc.Update(pvargs: any): bool

Parametre:

pvargs: En Ordbok som inneholder par med feltnavn og deres respektive verdier. Alternativt kan et partall av argumenter spesifiseres vekslende feltnavn (som en streng) og deres verdier.

Eksempel:

I Basic

Eksemplet nedenfor oppdaterer gjeldende post ved hjelp av en Ordbok.


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

Det samme resultatet kan oppnås ved å sende alle par av felt og verdier som argumenter:


      oDataset.Update("Age", 51, "City", "New York")

I Python


      new_values = {"Age": 51, "City": "New York"}
      dataset.Update(new_values)


      dataset.Update("Age", 51, "City", "New York")
      dataset.Update(Age = 51, City = "New York")

Alle ScriptForge Grunnleggende rutiner eller identifikatorer som er prefikset med et understrekingstegn "_" er reservert for intern bruk. De er ikke ment å brukes i grunnleggende makroer eller Python-skript.

SFDatabaser.Database-tjeneste