Inhalte

# Dienst SFDatabases.Dataset

Der Dienst Dataset wird zur Darstellung tabellarischer Daten verwendet, die von einer Datenbank erstellt werden. Mit diesem Service ist es möglich:

- Durch die Daten in einem Datenbestand zu navigieren und darauf zuzugreifen.

- Datensätze in einem Datenbestand zu aktualisieren, einzufügen und zu entfernen.

Das Aktualisieren und Einfügen von Datensätzen mit dem Dienst Dataset ist langsamer als die Verwendung von SQL-Anweisungen. Beim Aktualisieren oder Einfügen großer Mengen an Datensätzen wird empfohlen, SQL-Anweisungen anstelle der Methoden in diesem Dienst zu verwenden.

## Dienstaufruf

Vor der Verwendung des Dienstes Dataset muss die Bibliothek ScriptForge geladen oder importiert werden:

• Grundlegende Makros erfordern das Laden der Bibliothek ScriptForge mit der folgenden Anweisung:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python-Skripte erfordern einen Import aus dem Modul scriptforge:
from scriptforge import CreateScriptService

Der Dienst Dataset wird mit der Methode CreateDataset aufgerufen, die entweder von einer Dienstinstanz Database oder von einer anderen Instanz Dataset.

##### In Basic

Im folgenden Beispiel wird ein Dataset aus der in einer Datenbankdatei gespeicherten Tabelle „Kunden“ erstellt.

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

Bei der Erstellung des Dataset wird der aktuelle Datensatz vor dem ersten Datensatz positioniert.

Im folgenden Beispiel wird eine Instanz Dataset erstellt, indem der ursprüngliche Datenbestand gefiltert wird.

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

##### In Python

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

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

## Eigenschaften

Name | Schreibgeschützt | Typ | Beschreibung
--- | --- | --- | ---
BOF | Nein | Boolean | Gibt True zurück, wenn die aktuelle Datensatzposition vor dem ersten Datensatz im Datenbestand liegt, andernfalls wird False zurückgegeben. Setzt diese Eigenschaft auf True, um den Cursor an den Anfang des Datenbestand zu bewegen. Das Setzen dieser Eigenschaft auf False wird ignoriert.
DefaultValues | Ja | Dienst Dictionary | Gibt ein Dictionary mit den Standardwerten zurück, die für jedes Feld im Datenbestand verwendet werden. Die Felder oder Spalten im Datenbestand sind die Schlüssel im Wörterbuch. Die Datenbankfeldtypen werden in die entsprechenden Basic-/Python-Datentypen konvertiert. Wenn der Feldtyp undefiniert ist, ist der Standardwert Null, wenn das Feld nullbar oder Empty ist.
EOF | Nein | Boolean | Gibt True zurück, wenn die aktuelle Datensatzposition nach dem letzten Datensatz im Datenbestand liegt, andernfalls wird False zurückgegeben. Setzen Sie diese Eigenschaft auf True, um den Cursor an das Ende des Datenbestandes zu bewegen. Das Setzen dieser Eigenschaft auf False wird ignoriert.
Fields | Ja | Array | Gibt eine Matrix zurück, das die Namen aller Felder im Datenbestand enthält.
Filter | Ja | String | Gibt den Filter zurück, der zusätzlich zu den eventuellen Klauseln WHERE in der anfänglichen SQL-Anweisung angewendet wird. Diese Eigenschaft wird als Klausel WHERE ohne das Schlüsselwort "WHERE" ausgedrückt.
OrderBy | Ja | String | Gibt die Sortierklausel zurück, die die eventuelle Klauseln ORDER BY in der ursprünglichen SQL-Anweisung ersetzt. Diese Eigenschaft wird als Klausel ORDER BY ohne die Schlüsselwörter "ORDER BY" ausgedrückt.
ParentDatabase | Ja | Dienst Database | Gibt die Instanz Database zurück, die der übergeordneten Datenbank des aktuellen Datenbestandes entspricht.
RowCount | Ja | Long | Gibt die genaue Anzahl der Datensätze im Datenbestand zurück. Beachten Sie, dass die Auswertung dieser Eigenschaft das Durchsuchen des gesamten Datenbestandes erfordert, was je nach Datenbestandsgröße langwierig sein kann.
RowNumber | Ja | Long | Gibt die Nummer des aktuellen Datensatzes beginnend bei 1 zurück. Gibt 0 zurück, wenn diese Eigenschaft unbekannt ist.
Source | Ja | String | Gibt die Quelle des Datenbestandes zurück. Dabei kann es sich entweder um einen Tabellennamen, einen Abfragenamen oder eine SQL-Anweisung handeln.
SourceType | Ja | String | Gibt die Quelle des Datenbestandes zurück. Es kann eine der folgenden Zeichenfolgen sein: TABLE, QUERY oder SQL.
UpdatableFields | Ja | Array | Gibt eine Matrix zurück, welche die Namen der Felder des Datenbestandes enthält, die aktualisierbar sind.
Values | Ja | Array | Gibt ein Dictionary zurück, das die Paare (Feldname:Wert) des aktuellen Datensatzes im Datenbestand enthält.
XRowSet | Ja | UNO-Objekt | Gibt das UNO-Objekt com.sun.star.sdb.RowSet zurück, das den Datenbestand darstellt.

Liste der Methoden im Service "Dataset"
CloseDataset CreateDataset Delete ExportValueToFile GetRows | GetValue Insert MoveFirst MoveLast | MoveNext MovePrevious Reload Update

## CloseDataset

Schließt den aktuellen Datenbestand. Diese Methode gibt bei Erfolg True zurück.

Es wird empfohlen, den Datenbestand nach seiner Verwendung zu schließen, um Ressourcen freizugeben.

### Syntax:

svc.CloseDataset(): bool

### Beispiel:

##### In Basic

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

##### In Python

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

## CreateDataset

Gibt eine Dienstinstanz Dataset aus einem vorhandenen Datenbestand zurück, indem der angegebene Filter und die Anweisung ORDER BY angewendet werden.

### Syntax:

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

### Parameter:

filter: Legt die Bedingung fest, die Datensätze erfüllen müssen, um in den zurückgegebenen Datenbestand aufgenommen zu werden. Dieses Argument wird als SQL-Anweisung WHERE ohne das Schlüsselwort "WHERE" ausgedrückt. Wenn dieses Argument nicht angegeben ist, wird der im aktuellen Datenbestand verwendete Filter angewendet, andernfalls wird der aktuelle Filter durch dieses Argument ersetzt.

orderby: Legt die Reihenfolge des Datenbestandes als SQL-Anweisung ORDER BY ohne das Schlüsselwort "ORDER BY" fest. Wenn dieses Argument nicht angegeben ist, wird die im aktuellen Datenbestand verwendete Sortierreihenfolge angewendet, andernfalls wird die aktuelle Sortierreihenfolge durch dieses Argument ersetzt.

### Beispiel:

##### In Basic

          ' Verwenden Sie eine leere Zeichenfolge, um den aktuellen Filter zu entfernen
          oNewDataset = oDataset.CreateDataset(Filter := "")
          ' Beispiele für gängige Filter
          oNewDataset = oDataset.CreateDataset(Filter := "[Name] = 'John'")
          oNewDataset = oDataset.CreateDataset(Filter := "[Name] LIKE 'A'")
          ' Es ist möglich, zusätzliche Bedingungen an den aktuellen Filter anzuhängen
          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

Löscht den aktuellen Datensatz aus dem Datenbestand. Diese Methode gibt bei Erfolg True zurück.

Nach diesem Vorgang wird der Cursor auf den Datensatz unmittelbar nach dem gelöschten Datensatz positioniert. Wenn der gelöschte Datensatz der letzte im Datenbestand ist, wird der Cursor danach positioniert und die Eigenschaft EOF gibt True zurück.

### Syntax:

svc.Delete(): bool

### Beispiel:

##### In Basic

          oDataset.Delete()

##### In Python

          dataset.Delete()

## ExportValueToFile

Exportiert den Wert eines Binärfelds des aktuellen Datensatzes in die angegebene Datei.

Wenn das angegebene Feld nicht binär ist oder keine Daten enthält, wird die Ausgabedatei nicht erstellt.

### Syntax:

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

### Parameter:

fieldname: Der Name des zu exportierenden Binärfelds als Zeichenfolge, bei der die Groß-/Kleinschreibung beachtet wird.

filename: Der vollständige Pfad zur zu erstellenden Datei unter Verwendung der in der Eigenschaft FileSystem.FileNaming festgelegten Schreibweise.

overwrite: Setzen Sie dieses Argument auf True, um das Überschreiben der Zieldatei zu ermöglichen (Standard = False).

### Beispiel:

Im folgenden Beispiel enthält der Datenbestand ein Feld mit dem Namen „Bild“, das in eine Bilddatei exportiert werden soll.

##### In Basic

          oDataset.ExportValueToFile("Bild", "C:\Mein_Bild.png", True)

##### In Python

          dataset.ExportValueToFile("Bild", r"C:\Mein_Bild.png", True)

## GetRows

Gibt den Inhalt des Datenbestandes in einer zweidimensionalen Matrix zurück, beginnend mit dem ersten Datensatz nach dem aktuellen Datensatz.

Nach der Ausführung wird der Cursor in der Zeile positioniert, die zuletzt gelesen wurde, oder nach dem letzten Datensatz des Datenbestandes. In diesem Fall gibt die Eigenschaft EOF True zurück.

Mit dieser Methode können Daten aus dem Datenbestand in Blöcken gelesen werden, deren Größe durch das Argument maxrows festgelegt wird.

Die zurückgegebene Matrix hat immer zwei Dimensionen, auch wenn der Datenbestand eine einzelne Spalte und einen einzelnen Datensatz enthält.

### Syntax:

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

### Parameter:

header: Setzen Sie dieses Argument auf True, damit der erste Eintrag in der Matrix die Spaltenüberschriften enthält (Standard = False).

maxrows: Definiert die maximale Anzahl der zurückzugebenden Datensätze. Wenn die Anzahl der vorhandenen Datensätze kleiner als maxrows ist, entspricht die Größe der zurückgegebenen Matrix der Anzahl der verbleibenden Datensätze im Datenbestand. Lassen Sie dieses Argument leer oder setzen Sie es auf Null, um alle Zeilen im Datenbestand zurückzugeben (Standard = 0).

### Beispiel:

Das folgende Beispiel liest einen Datenbestand in Blöcken von 100 Zeilen, bis der gesamte Datenbestand gelesen wurde.

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

Gibt den Wert des angegebenen Felds aus dem aktuellen Datensatz des Datenbestandes zurück.

Wenn das angegebene Feld binär ist, wird seine Länge zurückgegeben.

### Syntax:

svc.GetValue(fieldname: str): any

### Parameter:

fieldname: Der Name des zurückzugebenden Felds als Zeichenfolge, bei der die Groß-/Kleinschreibung beachtet wird.

### Beispiel:

##### In Basic

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

##### In Python

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

## Insert

Fügt einen neuen Datensatz am Ende des Datenbestandes ein und initialisiert seine Felder mit den angegebenen Werten.

Wenn der Primärschlüssel des Datensatzes ein automatischer Wert ist, gibt diese Methode den Primärschlüsselwert des neuen Datensatzes zurück. Andernfalls gibt die Methode 0 (bei Erfolg) oder -1 (bei Nichterfolg) zurück.

Aktualisierbare Felder mit nicht angegebenen Werten werden mit ihren Standardwerten initialisiert.

Wenn das angegebene Feld binär ist, wird seine Länge zurückgegeben.

### Syntax:

svc.Insert(pvargs: any): int

### Parameter:

pvargs: Ein Dictionary, das Paare von Feldnamen und ihren jeweiligen Werten enthält. Alternativ kann eine gerade Anzahl von Argumenten abwechselnd mit Feldnamen (als String) und deren Werten angegeben werden.

### Beispiel:

##### In Basic

Stellen Sie sich eine Tabelle mit dem Namen „Kunden“ mit vier Feldern vor: „ID“ (BigInt, automatischer Wert und Primärschlüssel), „Name“ (VarChar), „Alter“ (Integer), „Stadt“ (VarChar).

Das folgende Beispiel fügt mithilfe eines Dictionary einen neuen Datensatz in diesen Datenbestand ein.

          oDataset = oDatabase.CreateDataset("Kunden")
          oNewData = CreateScriptService("Dictionary")
          oNewData.Add("Name", "Jan")
          oNewData.Add("Alter", 50)
          oNewData.Add("Stadt", "Berlin")
          lNewID = oDataset.Insert(oNewData)

Das gleiche Ergebnis kann erreicht werden, indem alle Paare von Feldern und Werten als Argumente übergeben werden:

          oDataset.Insert("Name", "Jan", "Alter", 50, "Stadt", "Berlin")

##### In Python

          dataset = database.CreateDataset("Kunden")
          new_data = {"Name": "Jan", "Alter": 30, "Stadt": "Berlin"}
          new_id = dataset.Insert(new_data)

Folgende Aufrufe werden in Python akzeptiert:

          dataset.Insert("Name", "Jan", "Alter", 50, "Stadt", "Berlin")
          dataset.Insert(Name = "Jan", Alter = 50, Stadt = "Berlin")

## MoveFirst / MoveLast

Bewegt den Datenbestandscursor zum ersten (mit MoveFirst) oder zum letzten (mit MoveLast) Datensatz.

Diese Methode gibt bei Erfolg True zurück.

Gelöschte Datensätze werden von dieser Methode ignoriert.

### Syntax:

svc.MoveFirst(): bool

svc.MoveLast(): bool

### Beispiel:

##### In Basic

          oDataset.MoveFirst()

##### In Python

          dataset.MoveFirst()

## MoveNext / MovePrevious

Bewegt den Datenbestandscursor um eine bestimmte Anzahl von Datensätzen vorwärts (mit MoveNext) oder rückwärts (mit MovePrevious).

Diese Methode gibt bei Erfolg True zurück.

Gelöschte Datensätze werden von dieser Methode ignoriert.

### Syntax:

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

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

### Parameter:

offset: Die Anzahl der Datensätze, um die der Cursor vorwärts oder rückwärts bewegt werden soll. Dieses Argument kann ein negativer Wert sein (Standard = 1).

### Beispiel:

##### In Basic

          oDataset.MoveNext()
          oDataset.MoveNext(5)

##### In Python

          dataset.MoveNext()
          dataset.MoveNext(5)

## Reload

Lädt den Datenbestand neu aus der Datenbank. Beim Aufruf dieser Methode können die Eigenschaften Filter und OrderBy festgelegt werden.

Diese Methode gibt bei Erfolg True zurück.

Das Neuladen des Datenbestandes ist nützlich, wenn Datensätze in die Datenbank eingefügt oder daraus gelöscht wurden. Beachten Sie, dass die Methoden CreateDataset und Reload ähnliche Funktionen ausführen, Reload jedoch dieselbe Klasseninstanz Dataset wiederverwendet.

### Syntax:

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

### Parameter:

filter: Legt die Bedingung fest, die Datensätze erfüllen müssen, um in den zurückgegebenen Datenbestand aufgenommen zu werden. Dieses Argument wird als SQL-Anweisung WHERE ohne das Schlüsselwort "WHERE" ausgedrückt. Wenn dieses Argument nicht angegeben ist, wird der im aktuellen Datenbestand verwendete Filter angewendet, andernfalls wird der aktuelle Filter durch dieses Argument ersetzt.

orderby: Legt die Reihenfolge des Datenbestandes als SQL-Anweisung ORDER BY ohne das Schlüsselwort "ORDER BY" fest. Wenn dieses Argument nicht angegeben ist, wird die im aktuellen Datenbestand verwendete Sortierreihenfolge angewendet, andernfalls wird die aktuelle Sortierreihenfolge durch dieses Argument ersetzt.

### Beispiel:

##### In Basic

          oDataset.Reload()
          oDataset.Reload(Filter := "[Name] = 'Jan'", OrderBy := "Alter")

##### In Python

          dataset.Reload()
          dataset.Reload(Filter = "[Name] = 'Jan'", OrderBy = "Alter")

## Update

Aktualisiert die Werte der angegebenen Felder im aktuellen Datensatz.

Diese Methode gibt bei Erfolg True zurück.

### Syntax:

svc.Update(pvargs: any): bool

### Parameter:

pvargs: Ein Dictionary, das Paare von Feldnamen und ihren jeweiligen Werten enthält. Alternativ kann eine gerade Anzahl von Argumenten abwechselnd mit Feldnamen (als String) und deren Werten angegeben werden.

### Beispiel:

##### In Basic

Das folgende Beispiel aktualisiert den aktuellen Datensatz mithilfe eines Dictionary.

          oNewValues = CreateScriptService("Dictionary")
          oNewValues.Add("Alter", 51)
          oNewValues.Add("Stadt", "Hamburg")
          oDataset.Update(oNewValues)

Das gleiche Ergebnis kann erreicht werden, indem alle Paare von Feldern und Werten als Argumente übergeben werden:

          oDataset.Update("Alter", 51, "Stadt", "Hamburg")

##### In Python

          new_values = {"Alter": 51, "Stadt": "Hamburg"}
          dataset.Update(new_values)

          dataset.Update("Alter", 51, "Stadt", "Hamburg")
          dataset.Update(Alter = 51, City = "Hamburg")

Alle ScriptForge Basic-Routinen oder Bezeichner, denen ein Unterstrich "_" vorangestellt ist, sind für den internen Gebrauch reserviert. Sie sind nicht für die Verwendung in Basic-Makros oder Python-Skripten vorgesehen.

Verwandte Themen

Dienst SFDatabases.Database