LibreOffice 25.2 Hjælp
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.
Før du bruger Dataset-tjenesten skal ScriptForge-biblioteket være indlæst eller importeret:
Tjenesten Dataset aktiveres med CreateDataset-metoden, som kan kaldes enten fra en Database-tjeneste eller fra en anden Dataset-instans.
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'")
  
    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'")
  | 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 | ||
|---|---|---|
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.
svc.CloseDataset(): bool
      oDataset = oDatabase.CreateDataset("MyTable")
      ' ...
      oDataset.CloseDataset()
    
      dataset = database.CreateDataset("MyTable")
      # ...
      dataset.CloseDataset()
    Returnerer en instans af Dataset-tjeneste ud fra et eksisterende datasæt ved at anvende de angivne filter og ORDER BY-udrykkene.
svc.CreateDataset(opt filter: str, opt orderby: str): svc
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.
      ' 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'")
    
      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'")
    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.
svc.Delete(): bool
      oDataset.Delete()
    
      dataset.Delete()
    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.
svc.ExportValueToFile(fieldname: str, filename: str, overwrite: bool): bool
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).
I eksemplet nedenfor indeholder datasættet et felt kaldt "Billede", som skal eksporteres til en billedfil.
      oDataset.ExportValueToFile("Billede", "C:\mit_billede.png", True)
    
      dataset.ExportValueToFile("Billede", r"C:\mit_billede.png", True)
    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.
svc.GetRows(header: bool, maxrows: int): any
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)
Det følgende eksempel læser et datasæt i bidder på 100 rækker indtil hele datasættet er blevet læst.
      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
    
      max_rows = 100
      chunk = dataset.GetRows(maxrows = max_rows)
      while len(chunk) > 0:
          # ...
          chunk = dataset.GetRows(maxrows = max_rows)
    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.
svc.GetValue(fieldname: str): any
fieldname: Navnet på feltet, der skal returneres, som en streng med forskel på store og små bogstaver.
      currId = oDataset.GetValue(FieldName := "ID")
    
      curr_id = dataset.GetValue(fieldname = "ID")
    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.
svc.Insert(pvargs: any): int
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.
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")
    
      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")
    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.
svc.MoveFirst(): bool
svc.MoveLast(): bool
      oDataset.MoveFirst()
    
      dataset.MoveFirst()
    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.
svc.MoveNext(offset: int = 1): bool
svc.MovePrevious(offset: int = 1): bool
offset: Antallet af poster, som markøren skal rykkes fremad eller tilbage. Dette argument kan være en negativ værdi (standard = 1).
      oDataset.MoveNext()
      oDataset.MoveNext(5)
    
      dataset.MoveNext()
      dataset.MoveNext(5)
    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.
svc.Reload(opt filter: str, opt orderby: str): bool
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.
      oDataset.Reload()
      oDataset.Reload(Filter := "[Navn] = 'John'", OrderBy := "Alder")
    
      dataset.Reload()
      dataset.Reload(Filter = "[Navn] = 'John'", OrderBy = "Alder")
    Opdatér værdierne af de angivne felter i den aktuelle datapost.
Denne metode returnerer True, når den lykkes.
svc.Update(pvargs: any): bool
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.
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")
    
      new_values = {"Alder": 51, "City": "Aarhus"}
      dataset.Update(new_values)
    
      dataset.Update("Alder", 51, "By", "Aarhus")
      dataset.Update(Alder = 51, By = "Aarhus")