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:

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.

Tjenesten SFDatabases.Database