SFDatabases.Dataset-tjeneste

Innhold

# 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 datasett ved å bruke det angitte filteret og ORDER BY-setningene.

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

          ' Bruk en tom streng for å fjerne gjeldende filter
          oNewDataset = oDataset.CreateDataset(Filter := "")
          Eksempler på vanlige filtre
          oNewDataset = oDataset.CreateDataset(Filter := "[Navn] = 'John'")
          oNewDataset = oDataset.CreateDataset(Filter := "[Navn] LIKE 'A'")
          ' Det er mulig å legge til flere betingelser til gjeldende filter
          oNewDataset = oDataset.CreateDataset(Filter := "(" & oDataset.Filter & ") OG [Navn] 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:

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

          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.

Lignende emner

SFDatabaser.Database-tjeneste