SFDatabases.Dataset-service

De service Dataset wordt gebruikt om tabelgegevens weer te geven die door een database worden geproduceerd. Met deze dienst is het mogelijk om:

Navigeer door en open de gegevens in een dataset.
Records in een dataset bijwerken, invoegen en verwijderen.

Het bijwerken en invoegen van records met de service Dataset is langzamer dan het gebruik van SQL-instructies. Bij het bijwerken van het invoegen van grote hoeveelheden records wordt aanbevolen om SQL-instructies te gebruiken in plaats van de methoden in deze service te gebruiken.

Service-aanroep

Voordat u de Dataset-service gebruikt, moet de ScriptForge-bibliotheek worden geladen of geïmporteerd:

• Basic macro's kunnen de bibliotheek ScriptForge laden met de instructie:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python scripts kunnen de module scriptforge importeren met:
from scriptforge import CreateScriptService

De Dataset-service wordt aangeroepen met behulp van de CreateDataset-methode, die kan worden aangeroepen vanuit een Database-service-instantie of vanuit een andere Datasetinstance.

In BASIC

In het volgende voorbeeld wordt een Dataset gemaakt uit de tabel "Klanten", opgeslagen in een databasebestand.


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

Bij het aanmaken van de Dataset wordt het huidige record vóór het eerste record geplaatst.

In het onderstaande voorbeeld wordt een Dataset-instantie gemaakt door de oorspronkelijke dataset te filteren.


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

In Python


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


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

Eigenschappen

Naam	Alleen-lezen	Type	Beschrijving
BOF	Nee	Boolean	Retourneert True als de huidige recordpositie vóór het eerste record in de gegevensset ligt, en retourneert anders False. Stel deze eigenschap in op True om de cursor naar het begin van de gegevensset te verplaatsen. Het instellen van deze eigenschap op False wordt genegeerd.
DefaultValues	Ja	Dictionary-service	Retourneert een Woordenboek met de standaardwaarden die voor elk veld in de dataset worden gebruikt. De velden of kolommen in de dataset zijn de sleutels in het woordenboek. De databaseveldtypen worden geconverteerd naar de overeenkomstige Basic/Python-gegevenstypen. Als het veldtype niet gedefinieerd is, is de standaardwaarde Null als het veld nullable is, of Empty.
EOF	Nee	Boolean	Retourneert True als de huidige recordpositie na het laatste record in de gegevensset ligt, en retourneert anders False. Stel deze eigenschap in op True om de cursor naar het einde van de gegevensset te verplaatsen. Het instellen van deze eigenschap op False wordt genegeerd.
Fields	Ja	Array	Retourneert een Array met de namen van alle velden in de gegevensset.
Filter	Ja	String	Retourneert het filter dat is toegepast naast de eventuele WHERE-clausule(s) in de initiële SQL-instructie. Deze eigenschap wordt uitgedrukt als een WHERE-clausule zonder het trefwoord "WHERE".
OrderBy	Ja	String	Retourneert de ordeningsclausule die de eventuele ORDER BY-clausule vervangt die aanwezig is in de initiële SQL-instructie. Deze eigenschap wordt uitgedrukt als een ORDER BY-clausule zonder de trefwoorden "ORDER BY".
ParentDatabase	Ja	Database-service	Retourneert de Database-instantie die overeenkomt met de bovenliggende database van de huidige gegevensset.
RowCount	Ja	Long	Retourneert het exacte aantal records in de gegevensset. Houd er rekening mee dat de evaluatie van deze eigenschap impliceert dat u door de hele dataset moet bladeren, wat kostbaar kan zijn, afhankelijk van de grootte van de dataset.
RowNumber	Ja	Long	Retourneert het nummer van de huidige record, beginnend bij 1. Retourneert 0 als deze eigenschap onbekend is.
Source	Ja	String	Retourneert de bron van de gegevensset. Dit kan een tabelnaam, een querynaam of een SQL-instructie zijn.
SourceType	Ja	String	Retourneert de bron van de gegevensset. Het kan een van de volgende tekenreekswaarden zijn: TABLE, QUERY of SQL.
UpdatableFields	Ja	Array	Retourneert een Array met de namen van de velden van de gegevensset die kunnen worden bijgewerkt.
Values	Ja	Array	Retourneert een Woordenboek met de paren (veldnaam: waarde) van het huidige record in de gegevensset.
XRowSet	Ja	UNO-object	Retourneert de com.sun.star.sdb.RowSet UNO-object die de dataset vertegenwoordigt.

Lijst met methoden in de Dataset-service
CloseDataset CreateDataset Delete ExportValueToFile GetRows	GetValue Insert MoveFirst MoveLast	MoveNext MovePrevious Reload Update

CloseDataset

Sluit de huidige gegevensset. Deze methode retourneert True als deze succesvol is.

Het wordt aanbevolen om de dataset na gebruik te sluiten om bronnen vrij te maken.

Syntaxis:

svc.CloseDataset(): bool

Voorbeeld:

In BASIC


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

In Python


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

CreateDataset

Retourneert een Dataset service-instantie uit een bestaande dataset door het opgegeven filter en de volgorde van instructies toe te passen.

Syntaxis:

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

Parameters:

filter: Specificeert de voorwaarde waaraan records moeten voldoen om te worden opgenomen in de geretourneerde dataset. Dit argument wordt uitgedrukt als een SQL WHERE-instructie zonder het trefwoord "WHERE". Als dit argument niet is opgegeven, wordt het filter toegepast dat in de huidige gegevensset wordt gebruikt; anders wordt het huidige filter vervangen door dit argument.

orderby: specificeert de volgorde van de gegevensset als een SQL ORDER BY-instructie zonder het trefwoord "ORDER BY". Als dit argument niet is opgegeven, wordt de sorteervolgorde toegepast die in de huidige dataset wordt gebruikt, anders wordt de huidige sorteervolgorde vervangen door dit argument.

Voorbeeld:

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

In 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

Verwijdert het huidige record uit de gegevensset. Deze methode retourneert True als deze succesvol is.

Na deze handeling wordt de cursor direct na het verwijderde record op het record geplaatst. Als het verwijderde record het laatste in de dataset is, wordt de cursor erna geplaatst en retourneert de eigenschap EOF True.

Syntaxis:

svc.Delete(): bool

Voorbeeld:

In BASIC


      oDataset.Delete()

In Python


      dataset.Delete()

ExportValueToFile

Exporteert de waarde van een binair veld van het huidige record naar het opgegeven bestand.

Als het opgegeven veld niet binair is of geen gegevens bevat, wordt het uitvoerbestand niet gemaakt.

Syntaxis:

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

Parameters:

fieldname: de naam van het binaire veld dat moet worden geëxporteerd, als een hoofdlettergevoelige tekenreeks.

filename: Het volledige pad naar het bestand dat moet worden gemaakt met behulp van de notatie die is gedefinieerd in de eigenschap FileSystem.FileNaming.

overwrite: Stel dit argument in op True om toe te staan dat het doelbestand wordt overschreven (Standaard = False).

Voorbeeld:

In het onderstaande voorbeeld bevat de dataset een veld met de naam "Afbeelding" dat naar een afbeeldingsbestand moet worden geëxporteerd.

In BASIC


      oDataset.ExportValueToFile("Afbeelding", "C:\my_image.png", True)

In Python


      dataset.ExportValueToFile("Afbeelding", r"C:\my_image.png", True)

GetRows

Retourneert de inhoud van de gegevensset in een tweedimensionale matrix, beginnend bij het eerste record na het huidige record.

Na uitvoering wordt de cursor in de rij geplaatst die het laatst is gelezen of na het laatste record in de dataset, in welk geval de eigenschap EOF True retourneert.

Deze methode kan worden gebruikt om gegevens uit de dataset in stukjes te lezen, waarvan de grootte wordt gedefinieerd door het argument maxrows.

De geretourneerde matrix heeft altijd twee dimensies, zelfs als de gegevensset één kolom en één record bevat.

Syntaxis:

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

Parameters:

header: Stel dit argument in op True om ervoor te zorgen dat de eerste invoer in de Array de kolomkoppen bevat (standaard = False).

maxrows: Definieert het maximale aantal records dat moet worden geretourneerd. Als het aantal bestaande records kleiner is dan maxrows, zal de grootte van de geretourneerde array gelijk zijn aan het aantal resterende records in de dataset. Laat dit argument leeg of stel het in op nul om alle rijen in de gegevensset te retourneren (standaard = 0)

Voorbeeld:

In het volgende voorbeeld wordt een gegevensset gelezen in blokken van 100 rijen totdat de gehele gegevensset is gelezen.

In 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

In Python


      max_rows = 100
      chunk = dataset.GetRows(maxrows = max_rows)
      while len(chunk) > 0:
          # ...
          chunk = dataset.GetRows(maxrows = max_rows)

GetValue

Retourneert de waarde van het opgegeven veld uit de huidige record van de gegevensset.

Als het opgegeven veld binair is, wordt de lengte ervan geretourneerd.

Syntaxis:

svc.GetValue(fieldname: str): any

Parameters:

fieldname: De naam van het veld dat moet worden geretourneerd, als een hoofdlettergevoelige tekenreeks.

Voorbeeld:

In BASIC


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

In Python


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

Insert

Voegt een nieuw record in aan het einde van de gegevensset en initialiseert de velden ervan met de opgegeven waarden.

Als de primaire sleutel van de gegevensset een automatische waarde is, retourneert deze methode de primaire sleutelwaarde van het nieuwe record. Anders retourneert de methode 0 (indien succesvol) of -1 (indien niet succesvol).

Bijwerkbare velden met niet-gespecificeerde waarden worden geïnitialiseerd met hun standaardwaarden.

Als het opgegeven veld binair is, wordt de lengte ervan geretourneerd.

Syntaxis:

svc.Insert(pvargs: any): int

Parameters:

pvargs: Een Woordenboek met paren veldnamen en hun respectieve waarden. Als alternatief kan een even aantal argumenten worden opgegeven met afwisselende veldnamen (als een Tekenreeks) en hun waarden.

Voorbeeld:

In BASIC

Beschouw een tabel met de naam 'Klanten' met vier velden: 'ID' (BigInt, automatische waarde en primaire sleutel), 'Naam' (VarChar), 'Leeftijd' (Geheel getal), "Plaats" (VarChar).

In het onderstaande voorbeeld wordt een nieuw record in deze dataset ingevoegd met behulp van een Woordenboek.


      oDataset = oDatabase.CreateDataset("Klanten")
      oNewData = CreateScriptService("Dictionary")
      oNewData.Add("Naam", "John")
      oNewData.Add("Leeftijd", 50)
      oNewData.Add("Stad", "Amsterdam")
      lNewID = oDataset.Insert(oNewData)

Hetzelfde resultaat kan worden bereikt door alle paren velden en waarden als argumenten door te geven:


      oDataset.Insert("Naam", "John", "Leeftijd", 50, "Stad", "Amsterdam")

In Python


      dataset = database.CreateDataset("Klanten")
      new_data = {"Naam": "John", "Leeftijd": 30, "Stad": "Amsterdam"}
      new_id = dataset.Insert(new_data)

De volgende oproepen worden geaccepteerd in Python:


      dataset.Insert("Naam", "John", "Leeftijd", 50, "Stad", "Amsterdam")
      dataset.Insert(Naam = "John", Leeftijd= 50, Stad= "Amsterdam")

MoveFirst / MoveLast

Verplaatst de gegevenssetcursor naar het eerste (met MoveFirst) of naar het laatste (met MoveLast) record.

Deze methode retourneert True als deze succesvol is.

Verwijderde records worden bij deze methode genegeerd.

Syntaxis:

svc.MoveFirst(): bool

svc.MoveLast(): bool

Voorbeeld:

In BASIC


      oDataset.MoveFirst()

In Python


      dataset.MoveFirst()

MoveNext / MovePrevious

Verplaatst de gegevenssetcursor vooruit (met MoveNext) of achteruit (met MovePrevious) met een bepaald aantal records.

Deze methode retourneert True als deze succesvol is.

Verwijderde records worden bij deze methode genegeerd.

Syntaxis:

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

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

Parameters:

offset: Het aantal records waarmee de cursor vooruit of achteruit moet worden verplaatst. Dit argument kan een negatieve waarde zijn (standaard = 1).

Voorbeeld:

In BASIC


      oDataset.MoveNext()
      oDataset.MoveNext(5)

In Python


      dataset.MoveNext()
      dataset.MoveNext(5)

Reload

Laadt de gegevensset opnieuw uit de database. De eigenschappen Filter en OrderBy kunnen worden gedefinieerd bij het aanroepen van deze methode.

Deze methode retourneert True als deze succesvol is.

Het opnieuw laden van de gegevensset is handig wanneer records in de database zijn ingevoegd of verwijderd. Houd er rekening mee dat de methoden CreateDataset en Reload soortgelijke functies uitvoeren, maar Reload gebruikt dezelfde klasse-instantie Dataset.

Syntaxis:

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

Parameters:

filter: Specificeert de voorwaarde waaraan records moeten voldoen om te worden opgenomen in de geretourneerde gegevensset. Dit argument wordt uitgedrukt als een SQL WHERE-instructie zonder het trefwoord "WHERE". Als dit argument niet is opgegeven, wordt het filter toegepast dat in de huidige gegevensset wordt gebruikt; anders wordt het huidige filter vervangen door dit argument.

orderby: Specificeert de volgorde van de gegevensset als een SQL-instructie ORDER BY zonder het trefwoord "ORDER BY". Als dit argument niet is opgegeven, wordt de sorteervolgorde toegepast die in de huidige gegevensset wordt gebruikt, anders wordt de huidige sorteervolgorde vervangen door dit argument.

Voorbeeld:

In BASIC


      oDataset.Reload()
      oDataset.Reload(Filter := "[Naam] = 'John'", OrderBy := "Leeftijd")

In Python


      dataset.Reload()
      dataset.Reload(Filter = "[Naam] = 'John'", OrderBy = "Leeftijd")

Update

Update de waarden van de opgegeven velden in het huidige record.

Deze methode retourneert True als deze succesvol is.

Syntaxis:

svc.Update(pvargs: any): bool

Parameters:

pvargs: Een Woordenboek met paren veldnamen en hun respectieve waarden. Als alternatief kan een even aantal argumenten worden opgegeven met afwisselende veldnamen (als een Tekenreeks) en hun waarden.

Voorbeeld:

In BASIC

In het onderstaande voorbeeld wordt de huidige record bijgewerkt met behulp van een Woordenboek.


      oNewValues = CreateScriptService("Dictionary")
      oNewValues.Add("Leeftijd", 51)
      oNewValues.Add("Stad", "Amsterdam")
      oDataset.Update(oNewValues)

Hetzelfde resultaat kan worden bereikt door alle paren velden en waarden als argumenten door te geven:


      oDataset.Update("Leeftijd", 51, "Stad", "Amsterdam")

In Python


      new_values = {"Leeftijd": 51, "Stad": "Amsterdam"}
      dataset.Update(new_values)


      dataset.Update("Leeftijd", 51, "Stad", "Amsterdam")
      dataset.Update(Leeftijd = 51, Stad = "Amsterdam")

Alle ScriptForge Basic-routines of variabelen die beginnen met een underscore "_" zijn voor intern gebruik. Gebruik deze niet in een Basic of Python-macro.

SFDatabases.Database-service