Indhold

# SFDatabases.Dataset-tjeneste

Tjenesten Dataset bruges til at repræsentere tabeldata produceret af en database. Med denne tjeneste er det muligt at:

- Navigere gennem og tilgå data i et datasæt.

- Opdatere, indsætte og fjerne poster i et datasæt.

Opdatering og indsættelse af poster med Dataset-tjenesten er langsommere end at bruge SQL-kommandoer. Når du opdaterer eller indsætter et stort antal poster, anbefales det at bruge SQL-kommandoer i stedet for at bruge metoderne i denne tjeneste.

## Tjenesteaktivering

Før du bruger Dataset-tjenesten skal ScriptForge-biblioteket være indlæst eller importeret:

• Basic-makroer kræver, at biblioteket ScriptForge indlæses med følgende udtryk:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python-scripts kræver import af scriptforge-modulet:
from scriptforge import CreateScriptService

Tjenesten Dataset aktiveres med CreateDataset-metoden, som kan kaldes enten fra en Database-tjeneste eller fra en anden Dataset-instans.

##### I Basic

Det følgende eksempel opretter et Dataset fra tabellen "Kunder" gemt 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 oprettelsen af Dataset står den aktuelle position i databasen før den første post.

Eksemplet nedenfor opretter en instans af Dataset ved at filtrere det oprindelige datasæt.

        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 = "[By]='København'")

## Egenskaber

Navn | Skrivebeskyttet | Type | Beskrivelse
--- | --- | --- | ---
BOF | Nej | Boolean | Returnerer True hvis den aktuelle postposition er før den første post i datasættet, ellers returneres False. Sæt denne egenskab til True for at flytte postpositionen til begyndelsen af datasættet. At sætte denne egenskab til False bliver ignoreret.
DefaultValues | Ja | Dictonary-tjeneste | Returnerer et Dictionary (en "ordbog", opslagstabel) med standardværdierne brugt i hvert felt i datasættet. Felterne eller kolonnerne i datasættet er nøgler i opslagstabellen. Felttyperne i databasen konverteres til deres tilsvarende Basic/Python-datatyper. Når felttypen er udefineret er standardværdien Null hvis feltet kan nulstilles, ellers Empty.
EOF | Nej | Boolean | Returnerer True hvis den aktuelle postposition er efter den sidste post i datasættet, ellers returneres False. Sæt denne egenskab til True for at flyttet postpositionen til slutningen af datasættet. At sætte denne egenskab til False bliver ignoreret.
Fields | Ja | Array | Returnerer et Array som indeholder navnene på alle felter i datasættet.
Filter | Ja | String | Returnerer det anvendte filter foruden den eventuelle WHERE-delsætning(er) i det oprindelige SQL-udtryk. Denne egenskab er udtrykt som en WHERE-delsætning uden nøgleordet "WHERE".
OrderBy | Ja | String | Returnerer den sorterings-delsætning som erstatter den eventuelle ORDER BY-delsætning i det oprindelige SQL-udtryk. Denne egenskab er udtrykt som en ORDER BY-delsætning uden nøgleordene "ORDER BY".
ParentDatabase | Ja | Database-tjeneste | Returnerer den Database-instans, som svarer til den overordnede database for det aktuelle datasæt.
RowCount | Ja | Long | Returnerer det nøjagtige antal poster i datasættet. Bemærk at evalueringen af denne egenskab involverer at hele datasættet gennemgås, hvilket kan være tidskrævende, afhængigt af datasættets størrelse.
RowNumber | Ja | Long | Returnerer nummeret på den aktuelle datapost, begyndende med 1. Returnerer 0 hvis denne egenskab er ukendt.
Source | Ja | String | Returnerer kilden til datasættet. Det kan enten være et tabelnavn, et forespørgselsnavn eller en SQL-sætning.
SourceType | Ja | String | Returnerer kildetypen til datasættet. Det kan være en af de følgende strengværdier: TABLE, QUERY eller SQL.
UpdatableFields | Ja | Array | Returnerer et Array med navnene på de felter i databasen, som kan opdateres.
Values | Ja | Array | Returnerer et Dictionary som indeholder parrene (feltnavn: værdi) for den aktuelle post i datasættet.
XRowSet | Ja | UNO-objekt | Returnerer UNO-objektet com.sun.star.sdb.RowSet, som repræsenterer datasættet.

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

## CloseDataset

Lukker det aktuelle datasæt. Denne metode returnerer True, når den lykkes.

Det anbefales at lukke datasættet efter brug for at frigøre ressourcer.

### Syntaks:

svc.CloseDataset(): bool

### Eksempel:

##### I Basic

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

##### I Python

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

## CreateDataset

Returnerer en instans af Dataset-tjeneste ud fra et eksisterende datasæt ved at anvende de angivne filter og ORDER BY-udrykkene.

### Syntaks:

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

### Parametre:

filter: Specificerer den betingelse, som dataposter skal matche for at blive inkluderet i det returnerede datasæt. Dette argument er udtrykt som et SQL WHERE-udtryk uden nøgleordet "WHERE". Hvis dette argument er udeladt, bruges filteret fra det aktuelle datasæt, og ellers bliver det aktuelle filter erstattet af dette argument.

orderby: Angiver sorteringsrækkefølgen af datasættet som et SQL ORDER BY-udtryk uden nøgleordet "ORDER BY". Hvis dette argument er udeladt, bruges sorteringsrækkefølgen fra det aktuelle datasæt, ellers bliver den aktuelle sorteringsrækkefølge erstattet af dette argument.

### Eksempel:

##### I Basic

          ' Brug en tom streng til at fjerne det aktuelle filter
          oNewDataset = oDataset.CreateDataset(Filter := "")
          ' Eksempler på typiske filtre
          oNewDataset = oDataset.CreateDataset(Filter := "[Navn] = 'John'")
          oNewDataset = oDataset.CreateDataset(Filter := "[Navn] LIKE 'A'")
          ' Det er muligt at tilføje yderligere betingelser til det aktuelle filter
          oNewDataset = oDataset.CreateDataset(Filter := "(" & oDataset.Filter & ") AND [Navn] LIKE 'A'")

##### I Python

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

## Delete

Sletter den aktuelle datapost fra datasættet. Denne metode returnerer True, når den lykkes.

Efter denne operation er markøren placeret ved dataposten umiddelbart efter den slettede datapost. Hvis den slettede datapost var den sidste i datasættet, så er markøren placeret efter sidste post, og egenskaben EOF returnerer True.

### Syntaks:

svc.Delete(): bool

### Eksempel:

##### I Basic

          oDataset.Delete()

##### I Python

          dataset.Delete()

## ExportValueToFile

Eksporterer værdien af et binært felt for den aktuelle datapost til den angivne fil.

Hvis det angivne felt ikke er binært eller hvis det ikke indeholder data, så bliver outputfilen ikke oprettet.

### Syntaks:

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

### Parametre:

fieldname: Navnet på det binære felt, der skal eksporteres, som en streng med forskel på store og små bogstaver.

filename: Den fuldstændige sti til den fil, som skal oprettes, med notationen defineret i egenskaben FileSystem.FileNaming.

overwrite: Sæt dette argument til True for at tillade at destinationsfilen overskrives, hvis den eksisterer i forvejen (standard = False).

### Eksempel:

I eksemplet nedenfor indeholder datasættet et felt kaldt "Billede", som skal eksporteres til en billedfil.

##### I Basic

          oDataset.ExportValueToFile("Billede", "C:\mit_billede.png", True)

##### I Python

          dataset.ExportValueToFile("Billede", r"C:\mit_billede.png", True)

## GetRows

Returnerer indholdet af datasættet som et 2-dimensionelt array, begyndende med den første datapost efter den aktuelle datapost.

Efter udførslen er markøren placeret ved den række som blev læst sidst, eller efter den sidste datapost i datasættet, i hvilket tilfælde EOF-egenskaben returnerer True.

Denne metode kan bruges til at læse data fra datasættet i bidder, hvis størrelse er defineret af argumentet maxrows.

Det returnerede array vil altid have to dimensioner, selv hvis datasættet kun indeholder en enkelt kolonne og en enkelt datapost.

### Syntaks:

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

### Parametre:

header: Sæt dette argument til True for at få den første opførsel i Array til at indeholde kolonneoverskrifter (standard = False).

maxrows: Definerer det maksimale antal poster, som vil blive returneret. Hvis antallet af eksisterende dataposter er lavere end maxrow, så vil størrelsen af det returnerede array være lig med antallet af poster i datasættet. Udelad dette argument, eller sæt det til nul, for at returnere alle rækker i datasættet (standard = 0)

### Eksempel:

Det følgende eksempel læser et datasæt i bidder på 100 rækker indtil hele datasættet er blevet læst.

##### 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 værdien af det angivne felt fra den aktuelle post i datasættet.

Hvis det angivne felt er binært, så bliver dets længde returneret.

### Syntaks:

svc.GetValue(fieldname: str): any

### Parametre:

fieldname: Navnet på feltet, der skal returneres, som en streng med forskel på store og små bogstaver.

### Eksempel:

##### I Basic

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

##### I Python

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

## Insert

Indsætter en ny post ved slutningen af datasættet, og initialiserer postens felter med de angivne værdier.

Hvis primærnøglen for datasættet er en automatisk værdi, så returnerer denne metode værdien af primærnøglen for den nye datapost. Ellers vil metoden returnere 0 (når den lykkes) eller -1 (når den ikke lykkes).

Opdaterbare felter med uspecificerede værdi bliver initialiserede med deres standardværdier.

Hvis det angivne felt er binært, så returneres feltets længde.

### Syntaks:

svc.Insert(pvargs: any): int

### Parametre:

pvargs: Et Dictionary (ordbog, opslagstabel) som indeholder par af feltnavne og deres tilhørende værdier. Alternativt kan angives et lige antal argumenter med skiftevis feltnavne (som en String) og deres værdier.

### Eksempel:

##### I Basic

Tænk på en tabel med navnet "Kunder", som har 4 felter: "ID" (BigIint, automatisk værdi og primærnøgle), "Navn" (VarChar), "Alder" (Integer), "By" (VarChar).

Eksemplet nedenfor indsætter en ny post i dette datasæt med brug af et Dictionary.

          oDataset = oDatabase.CreateDataset("Kunder")
          oNewData = CreateScriptService("Dictionary")
          oNewData.Add("Navn", "John")
          oNewData.Add("Alder", 50)
          oNewData.Add("By", "København")
          lNewID = oDataset.Insert(oNewData)

Det samme resultat kan opnås ved at sende alle par af felter og værdier som argumenter:

          oDataset.Insert("Navn", "John", "Alder", 50, "By", "København")

##### I Python

          dataset = database.CreateDataset("Kunder")
          new_data = {"Navn": "John", "Alder": 30, "By": "København"}
          new_id = dataset.Insert(new_data)

De følgende kald accepteres i Python:

          dataset.Insert("Navn", "John", "Alder", 50, "By", "København")
          dataset.Insert(Navn = "John", Alder = 50, By = "København")

## MoveFirst / MoveLast

Flytter datasæt-markøren til den første (med MoveFirst) eller den sidste (med MoveLast) post.

Denne metode returnerer True, når den lykkes.

Slettede dataposter ignoreres af denne metode.

### Syntaks:

svc.MoveFirst(): bool

svc.MoveLast(): bool

### Eksempel:

##### I Basic

          oDataset.MoveFirst()

##### I Python

          dataset.MoveFirst()

## MoveNext / MovePrevious

Flytter datasæt-markøren fremad (med MoveNext) eller bagud (med MovePrevious) med et angivet antal af poster.

Denne metode returnerer True, når den lykkes.

Slettede dataposter ignoreres af denne metode.

### Syntaks:

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

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

### Parametre:

offset: Antallet af poster, som markøren skal rykkes fremad eller tilbage. Dette argument kan være en negativ værdi (standard = 1).

### Eksempel:

##### I Basic

          oDataset.MoveNext()
          oDataset.MoveNext(5)

##### I Python

          dataset.MoveNext()
          dataset.MoveNext(5)

## Reload

Genindlæser datasættet fra databasen Egenskaberne Filter og OrderBy kan defineres, når du kalder denne metode.

Denne metode returnerer True, når den lykkes.

Genindlæsning af datasættet er nyttigt, når poster er blevet indsat i eller slettet fra databasen. Bemærk at metoderne CreateDataset og Reload udfører lignende funktioner, imidlertid genbruger Reload den samme instans af Dataset-klassen.

### Syntaks:

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

### Parametre:

filter: Angiver den betingelse, som poster skal opfylde for at blive inkluderet i det returnerede datasæt. Dette argument er udtrykt som et SQL WHERE-udtryk uden nøgleordet "WHERE". Hvis dette argument ikke er angivet, så bruges filteret fra det aktuelle datasæt, ellers erstattes det aktuelle filter med dette argument.

orderby: Angiver rækkefølge af datasættet som et SQL ORDER BY-udtryk uden nøgleordet "ORDER BY". Hvis dette argument ikke er angivet, så bruges sorteringsrækkefølge fra det aktuelle datasæt, ellers bliver den aktuelle sorteringsrækkefølge erstattet af dette argument.

### Eksempel:

##### I Basic

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

##### I Python

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

## Update

Opdatér værdierne af de angivne felter i den aktuelle datapost.

Denne metode returnerer True, når den lykkes.

### Syntaks:

svc.Update(pvargs: any): bool

### Parametre:

pvargs: Et Dictionary (ordbog, opslagstabel) som indeholder par af feltnavne og deres tilhørende værdier. Alternativt kan angives et lige antal argumenter med skiftevis feltnavne (som en String) og deres værdier.

### Eksempel:

##### I Basic

Eksemplet nedenfor opdaterer den aktuelle datapost ved hjælp af et Dictionary.

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

Det samme resultat kan opnås ved at sende alle par af felter og værdier som argumenter:

          oDataset.Update("Alder", 51, "By", "Aarhus")

##### I Python

          new_values = {"Alder": 51, "City": "Aarhus"}
          dataset.Update(new_values)

          dataset.Update("Alder", 51, "By", "Aarhus")
          dataset.Update(Alder = 51, By = "Aarhus")

Alle ScriptForge Basic-rutiner eller identifikatorer, der indledes med et understregstegn "_" er reserveret til internt brug. Det er ikke meningen, at de skal bruges i Basic-makroer eller Python-scripts.

Relaterede emner

Tjenesten SFDatabases.Database