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 Datensatz verwendet werden. Die Felder oder Spalten im Datensatz 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 Datensatz zurück, indem die angegebenen Filter- und Sortieranweisungen 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


      ' 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

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:

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:

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.

Dienst SFDatabases.Database