Inhoud

# 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 methodes 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 standaardwaardes die voor elk veld in de gegevensset worden gebruikt. De velden of kolommen in de gegevensset zijn de sleutels in het woordenboek. De databaseveldtypes worden geconverteerd naar de overeenkomstige Basic/Python-gegevenstypes. 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 één van de volgende tekenreekswaardes 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 methodes 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 service-instantie Gegevensset uit een bestaande dataset door het opgegeven filter en de ORDER BY-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

          ' Gebruik een lege tekenreeks om het huidige filter te verwijderen
          oNewDataset = oDataset.CreateDataset(Filter := "")
          ' Voorbeelden van veel voorkomende filters
          oNewDataset = oDataset.CreateDataset(Filter := "[Naam] = 'John'")
          oNewDataset = oDataset.CreateDataset(Filter := "[Naam] LIKE 'A'")
          ' Het is mogelijk om aanvullende voorwaarden aan het huidige filter toe te voegen
          oNewDataset = oDataset.CreateDataset(Filter := "(" & oDataset.Filter & ") EN [Naam] 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 matrix 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 waardes.

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 waardes worden geïnitialiseerd met hun standaardwaardes.

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 waardes. Als alternatief kan een even aantal argumenten worden opgegeven met afwisselende veldnamen (als een Tekenreeks) en hun waardes.

### 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 waardes 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 methodes 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 waardes 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 waardes. Als alternatief kan een even aantal argumenten worden opgegeven met afwisselende veldnamen (als een Tekenreeks) en hun waardes.

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

Verwante onderwerpen

SFDatabases.Database-service