DataSet – Erweiterte Funktionen
3.1.33 IAutoDataSet8 Interface
Von IAutoDataSet7 abstammendes Interface.
IDL
[ uuid(F960A8BC-9182-4D40-9B04-D82D554D8842), version(1.0), dual, oleautomation ]
interface IAutoDataSet8 : IAutoDataSet7;
Beschreibung
Ab Build: 3670.
IAutoDataSet8 Eigenschaften
Die folgende Tabelle zeigt die Eigenschaften von IAutoDataSet8.
Methoden
| Name | Beschreibung |
|---|---|
| Alle Methoden aus IAutoDataSet7 | |
| SetupLtzAendDat | SetupLtzAend ermöglicht das Schreiben eines unabhängigen Datumswertes für den Index LtzAend. |
Eigenschaften
| Name | Beschreibung |
|---|---|
| Alle Eigenschaften aus IAutoDataSet7 |
IAutoDataSet8::SetupLtzAendDat Methode
SetupLtzAend ermöglicht das Schreiben eines unabhängigen Datumswertes für den Index LtzAend.
IDL
[id(0x000003EA)]
HRESULT _stdcall SetupLtzAendDat([in] DATE LtzAend);
Beschreibung
Diese Funktion dient dazu, bei einem Abgleich von Daten aus einem anderen System als Änderungszeitpunkt die Zeit des externen Systems für die letzte Änderung heranzuziehen.
Hinweis
Sollte also ein erster Post nicht gelingen, können weitere Versuche ausgeführt werden, ohne den Wert neu setzen zu müssen.
Parameter
| Parameter | Beschreibung |
|---|---|
| [in] DATE LtzAend | Der Datumswert, der als letzte Änderung geschrieben werden soll |
3.1.34 IAutoDataSet9 Interface
Von IAutoDataSet8 abstammendes Interface.
IDL
[ uuid(4B933656-FA82-4FE5-BFF3-39EDF0B73B71), version(1.0), dual, oleautomation ]
interface IAutoDataSet9 : IAutoDataSet8;
Beschreibung
Ab Build: 3821.
IAutoDataSet9 Eigenschaften
Die folgende Tabelle zeigt die Eigenschaften von IAutoDataSet9.
Methoden
| Name | Beschreibung |
|---|---|
| Alle Methoden aus IAutoDataSet8 | |
| StartSnapShotTransaction | DB v2 – Die Funktion StartSnapShotTransaction erstellt von der aktuellen Tabelle ein persistente "Kopie" zum Zeitpunkt an dem die Funktion aufgerufen wird. |
| EndSnapShotTransaction | DB v2 – Die Funktion EndSnapShotTransaction hebt eine mit StartSnapShotTransaction erstellte persistente "Kopie" auf. |
| CachedOptimumReadOn | DB v2 – Die Funktion CachedOptimumReadOn versetzt die Verbindung zur Datenbank in einen Forward only Lesemodus mit verbesserter Performance. |
| CachedOptimumReadOff | DB v2 – Die Funktion CachedOptimumReadOff hebt den Forward only Lesemodus einer Datenbankverbindung auf. |
| CachedNext | DB v2 – Die Funktion CachedNext kann nur in Verbindung mit CachedOptimumReadOn verwendet werden. Sie ist für den "schnellen Vorlauf" zuständig. |
Eigenschaften
| Name | Beschreibung |
|---|---|
| Alle Eigenschaften aus IAutoDataSet8 |
IAutoDataSet9::StartSnapShotTransaction Methode
DB v2
Die Funktion StartSnapShotTransaction erstellt von der aktuellen Tabelle ein persistente "Kopie" zum Zeitpunkt an dem die Funktion aufgerufen wird.
IDL
[id(0x0000044D)]
HRESULT _stdcall StartSnapShotTransaction();
Beschreibung
StartSnapShotTransaction "friert" praktisch die Tabelle ein. Es wird eine konsistente Datenmenge hergestellt, die den Datenbestand zum Zeitpunkt des Aufrufes von StartSnapShotTransaction enthält. Man kann sozusagen von einer Kopie der Tabelle zum Aufrufzeitpunkt der Funktion sprechen.
Jeder Start-Aufruf benötigt seinen korrespondierenden End-Aufruf. Es ist wichtig, dass auch im Fehlerfall EndSnapShotTransaction aufgerufen wird, damit der Server seine Kopie der Tabelle aufräumen kann.
Delphi-Beispiel: SnapShot-Transaktion
BpTbl.StartSnapshotTransaction;
try
//arbeiten mit nur Lese Operationen
finally
BpTbl.EndSnapShotTransaction;
end;
Delphi-Beispiel: Experimenteller Nachweis der Isolation
BpTbl.StartSnapshotTransaction;
try
Showmessage(IntToStr(BpTbl.RecordCount) + ' Jetzt ist DIE Chance einen neuen Datensatz anzulegen');
// einen neuen Datensatz außerhalb dieser Routine anlegen
Showmessage(IntToStr(BpTbl.RecordCount) + ' Sind noch genauso viele wie zuvor!');
// trotz dem neuen Datensatz in den "Livedaten" bleibt der RecordCount identisch
finally
BpTbl.EndSnapShotTransaction;
end;
IAutoDataSet9::EndSnapShotTransaction Methode
DB v2
Die Funktion EndSnapShotTransaction hebt eine mit StartSnapShotTransaction erstellte persistente "Kopie" auf.
IDL
[id(0x0000044E)]
HRESULT _stdcall EndSnapShotTransaction();
Beschreibung
EndSnapShotTransaction muss nach jedem StartSnapShotTransaction aufgerufen werden. Diese Funktion gibt die danach nicht mehr benötigte Kopie der Tabelle frei. Dadurch kann der Server mit dem Aufräumen seiner Daten beginnen.
IAutoDataSet9::CachedOptimumReadOn Methode
DB v2
Die Funktion CachedOptimumReadOn versetzt die Verbindung zur Datenbank in einen Forward only Lesemodus mit verbesserter Performance.
IDL
[id(0x0000044F)]
HRESULT _stdcall CachedOptimumReadOn();
Beschreibung
CachedOptimumReadOn nimmt keine Parameter entgegen. Sollte die aktuelle Datenmenge nicht in diesen Modus versetzt werden können, wird eine Fehlermeldung erzeugt. Sie sollten innerhalb dieses Modus nur den CachedNext Aufruf verwenden. Eine Tabelle, die mit einem Filter versehen ist, kann nicht in diesem Modus genutzt werden.
Delphi-Beispiel: CachedOptimumReadOn/-Off mit CachedNext
//BpTbl z.B.: in einen Range versetzen
BpTbl.First;
BpTbl.CachedOptimumReadOn;
try
for i := 0 to (MaxCount) do
begin
// lesende Datenzugriffe
BpTbl.CachedNext;
end;
finally
BpTbl.CachedOptimumReadOff;
end;
Performance-Hinweis
Diese Funktion spielt Ihre wahren Stärken bei einer Netzwerkverbindung zum Server aus. Stellen wir uns folgendes Szenario vor: Netzwerk zum Server hat 3 Millisekunden Latenz, 20 000 Anfragen. Setzt man jetzt dagegen das zuvor 20 000 Anfragen mit jeweils 3 Millisekunden notwendig waren und diese Anzahl jetzt auf 2000 gemindert werden kann spart man an der reinen Netzwerkszeit schon eine Menge Zeit ein. In diesem Beispiel wären es nun 60 Sekunden gegen 6 Sekunden. Die Reduktion der Netzwerkanfragen macht bei dieser Art des Zugriffs den Löwenanteil aus. Jede microtech ERP Datenbank hat aufgrund Ihres Aufbaus einen anderen Faktor bei der Ersparnis der Anfragen.
IAutoDataSet9::CachedOptimumReadOff Methode
DB v2
Die Funktion CachedOptimumReadOff hebt den Forward only Lesemodus einer Datenbankverbindung auf.
IDL
[id(0x00000450)]
HRESULT _stdcall CachedOptimumReadOff();
Beschreibung
CachedOptimumReadOff nimmt keine Parameter entgegen. Diese Funktion hebt für die Tabelle den Forward only Modus auf. Jeder Aufruf von CachedOptimumReadOn benötigt seinen korrespondierenden Aufruf von CachedOptimumReadOff.
IAutoDataSet9::CachedNext Methode
DB v2
Die Funktion CachedNext kann nur in Verbindung mit CachedOptimumReadOn verwendet werden. Sie ist für den "schnellen Vorlauf" zuständig.
IDL
[id(0x00000451)]
HRESULT _stdcall CachedNext();
Beschreibung
Diese Funktion bewegt den Datensatzzeiger eine Zeile weiter in Richtung Ende. Die Funktion kann nur in einer Tabelle verwendet werden die mit CachedOptimumReadOn in einen Forward only Modus versetzt wurde.
3.1.35 IAutoDataset10 Interface
Von IAutoDataSet9 abstammendes Interface.
IDL
[ uuid(C6179204-0657-4F35-8E6F-B04EBD49ACAE), version(1.0), dual, oleautomation ]
interface IAutoDataset10 : IAutoDataSet9;
Beschreibung
Ab Build: 5000.
IAutoDataset10 Eigenschaften
Die folgende Tabelle zeigt die Eigenschaften von IAutoDataset10.
Methoden
| Name | Beschreibung |
|---|---|
| Alle Methoden aus IAutoDataSet9 | |
| WildcardRange | Wildcard Suche. |
Eigenschaften
| Name | Beschreibung |
|---|---|
| Alle Eigenschaften aus IAutoDataSet9 |
IAutoDataset10::WildcardRange Methode
Wildcard Suche.
IDL
[id(0x000004B1)]
HRESULT _stdcall WildcardRange([in] BSTR Search);
Beschreibung
Mit dieser Funktion kann eine Wildcard Suche durchgeführt werden. Die Suche funktioniert analog zu den Eingaben beispielsweise in Übersichtsformularen.
Bevor sie diese Funktion nutzen, sollten Sie sich im Klaren sein, welcher Index gewählt ist. Die Funktion wirkt auf das erste Feld im gewählten Index.
Delphi-Beispiel: WildcardRange
Tbl := BpApp.DataSetInfos('Adressen').CreateDataSetEx;
Tbl.Indices['Status'].Select;
Tbl.WildcardRange('?Ku');
Parameter
| Parameter | Beschreibung |
|---|---|
| [in] BSTR Search | String, der die Suche mit Wildcard beschreibt |
3.1.36 IAutoDataSet11 Interface
Von IAutoDataSet10 abstammendes Interface.
IDL
[ uuid(BD0F48F1-318C-4072-A08E-E2CAA8C297BF), version(1.0), dual, oleautomation ]
interface IAutoDataSet11 : IAutoDataset10;
Beschreibung
Ab Build: 5052.
IAutoDataSet11 Eigenschaften
Die folgende Tabelle zeigt die Eigenschaften von IAutoDataSet11.
Methoden
| Name | Beschreibung |
|---|---|
| Alle Methoden aus IAutoDataset10 | |
| SetupStatusPts | SetupStatusPts |
Eigenschaften
| Name | Beschreibung |
|---|---|
| Alle Eigenschaften aus IAutoDataset10 |
IAutoDataSet11::SetupStatusPts Methode
SetupStatusPts
IDL
[id(0x00000515)]
HRESULT _stdcall SetupStatusPts([out, retval] VARIANT_BOOL* Result);
Beschreibung
Die Funktion SetupStatusPts stellt für alle Tabellen, die eine Status PTS-Prüfung (ProTokollStatus) bieten, eine Routine bereit um diese Prüfung anzustoßen.
Anmerkung
Die Funktion kann zwar für alle Tabellen aufgerufen werden, Sinn macht es aber nur für Tabellen, die das Nested Dataset "PTS" enthalten.
Parameter
| Parameter | Beschreibung |
|---|---|
| [out, retval] VARIANT_BOOL* Result | "True", wenn erfolgreich |
3.1.37 IAutoDataSet12 Interface
Von IAutoDataSet11 abstammendes Interface.
IDL
[ uuid(352CE32A-C9DA-4D88-BC5C-C4F991CE99C5), version(1.0), dual, oleautomation ]
interface IAutoDataSet12 : IAutoDataSet11;
Beschreibung
Ab Build: 5630.
IAutoDataSet12 Eigenschaften
Die folgende Tabelle zeigt die Eigenschaften von IAutoDataSet12.
Methoden
| Name | Beschreibung |
|---|---|
| Alle Methoden aus IAutoDataSet11 | |
| CopyFromToHistory | CopyFromToHistory |
Eigenschaften
| Name | Beschreibung |
|---|---|
| Alle Eigenschaften aus IAutoDataSet11 |
IAutoDataSet12::CopyFromToHistory Methode
CopyFromToHistory
IDL
[id(0x00000579)]
HRESULT _stdcall CopyFromToHistory([out, retval] VARIANT_BOOL* Result);
Beschreibung
Diese Funktion kopiert den aktuellen Datensatz in die History beziehungsweise aus der History zurück.
Parameter
| Parameter | Beschreibung |
|---|---|
| [out, retval] VARIANT_BOOL* Result | True, wenn erfolgreich |
3.1.38 IAutoDataSet13 Interface
Von IAutoDataSet12 abstammendes Interface.
IDL
[ uuid(1514F90B-5DC1-4DF3-B208-D25F5F80E5E6), version(1.0), dual, oleautomation ]
interface IAutoDataSet13 : IAutoDataSet12;
Beschreibung
Ab Build: 5901 (Pre-Release v19)
IAutoDataSet13 Eigenschaften
Die folgende Tabelle zeigt die Eigenschaften von IAutoDataSet13.
Methoden
| Name | Beschreibung |
|---|---|
| Alle Methoden aus IAutoDataSet12 | |
| AcquireFieldList | Erzeugt eine Feldliste |
| ReleaseFieldList | Gibt eine Feldliste frei |
| ReadFieldListValues | Feldwerte abrufen |
| ReadFieldListValuesChunk | Ganzen Block von Daten abrufen |
| WriteFieldListValues | Feldwerte schreiben |
| FindKey | Sucht und springt auf einen Datensatz |
| SetRange | Setzt einen Range auf die Tabelle |
Eigenschaften
| Name | Beschreibung |
|---|---|
| Alle Eigenschaften aus IAutoDataSet12 |
IAutoDataSet13::AcquireFieldList Methode
Erzeugt eine Feldliste.
IDL
[id(0x000005DD)]
HRESULT _stdcall AcquireFieldList([in] BSTR Fields, [out, retval] long* Handle);
Beschreibung
Legt eine Feldliste an, die für die Methoden ReadFieldListValues, ReadFieldListValuesChunk und WriteFieldListValues verwendet wird.
Parameter
| Parameter | Beschreibung |
|---|---|
| [in] BSTR Fields | Damit legt man eine Feldliste an, <Name der Felder> enthält die Feldnamen der gewünschten Felder dieses DataSets. (Mit Komma oder Semikolon getrennt). Die Felder müssen in dem DataSet vorhanden sein. Bei den Feldnamen kann ein Werte-Typ angegeben werden, um die Werte spezifisch auszulesen. Der Feldtyp wird hinter den Feldnamen geschrieben und mit einem Doppelpunkt von ihm getrennt. Der Wertetyp kann einer dieser Typen sein (Gross-/Kleinschreibung ist nicht relevant): 'Integer', 'Int64', 'Float', 'String', 'Text', 'DisplayText', 'DateTime', 'Boolean', 'DataString', 'DataStream', 'DSReference', 'DSFileName', 'DSFileExtension', 'DataSet'. Syntax: "Feldname1;Feldname2:Integer;Feldname3;Feldname4:string;Feldname5". Falls ausschliesslich Felder abgefragt werden, die nicht vorhanden sind, wird -1 zurückgeliefert. |
| [out, retval] long* Handle | Handle der Feldliste für weitere Aufrufe |
IAutoDataSet13::ReleaseFieldList Methode
Gibt eine Feldliste frei.
IDL
[id(0x000005DE)]
HRESULT _stdcall ReleaseFieldList([in] long Handle);
Beschreibung
Gibt die zuvor mit AcquireFieldList angelegte Feldliste wieder frei.
Parameter
| Parameter | Beschreibung |
|---|---|
| [in] long Handle | Das Handle der Feldliste, welches man per AcquireFieldList erhalten hat |
IAutoDataSet13::ReadFieldListValues Methode
Feldwerte abrufen.
IDL
[id(0x000005DF)]
HRESULT _stdcall ReadFieldListValues([in] long Handle, [out, retval] VARIANT* Value);
Beschreibung
Die Werte im Array stehen in der Reihenfolge, die bei AcquireFieldList() angegeben wurde.
Parameter
| Parameter | Beschreibung |
|---|---|
| [in] long Handle | Das Handle der Feldliste, welches man per AcquireFieldList erhalten hat |
| [out, retval] VARIANT* Value | Varianten-Array mit den Werten |
IAutoDataSet13::ReadFieldListValuesChunk Methode
Ganzen Block von Daten abrufen.
IDL
[id(0x000005E0)]
HRESULT _stdcall ReadFieldListValuesChunk([in] long Handle, [in] short RequestCount, [out] long* ItemCount, [out, retval] VARIANT* Values);
Beschreibung
Damit kann man einen ganzen Block von Daten abfragen, z.B. die Werte der nächsten 500 Datensätze. Wenn weniger als die angefragten Datensätze zur Verfügung stehen, ist der ItemCount kleiner als der RequestCount.
Stehen keine Datensätze mehr zur Verfügung, ist der ItemCount = 0 und der Rückgabewert leer.
Parameter
| Parameter | Beschreibung |
|---|---|
| [in] long Handle | Das Handle der Feldliste, welches man per AcquireFieldList erhalten hat |
| [in] short RequestCount | Anzahl der angeforderten Datensätze |
| [out] long* ItemCount | Anzahl der zurückgelieferten Datensätze |
| [out, retval] VARIANT* Values | Varianten-Array auf ein Varianten-Array. Anmerkung: Felder mit dem Feldtyp DataSet können in diesem Modus nicht gelesen werden und der Rückgabe-Variant enthält den Wert Unassigned |
IAutoDataSet13::WriteFieldListValues Methode
Feldwerte schreiben.
IDL
[id(0x000005E1)]
HRESULT _stdcall WriteFieldListValues([in] long Handle, [in] VARIANT Values);
Beschreibung
Damit kann man in die mit AcquireFieldList angelegte Feldliste Werte schreiben.
Die Werte in dem Werte-Array müssen der Reihenfolge (und Datentyp) der Feldliste entsprechend und gleich viele Werte enthalten wie die Feldliste Felder enthält.
Nicht beschreibbare Felder (z.B. schreibgeschützte Felder, oder Felder mit den FeldTypen DataStream, DSReference, DSFileName, DSFileExtension, DataSet) werden ohne Meldung übergangen.
Besonderheit
Sofern man bei AcquireFieldList nur einen Feldnamen angegeben hat, kann man direkt den Feldwert angeben (d.h. man muss kein Variant-Array erzeugen).
Parameter
| Parameter | Beschreibung |
|---|---|
| [in] long Handle | Das Handle der Feldliste, welches man per AcquireFieldList erhalten hat |
| [in] VARIANT Values | Variant-Array |
IAutoDataSet13::FindKey Methode
Sucht und springt auf einen Datensatz.
IDL
[id(0x000005E2)]
HRESULT _stdcall FindKey([in] BSTR IndexName, [in] VARIANT KeyValues, [out, retval] VARIANT_BOOL* Result);
Beschreibung
Über diese Funktion kann sehr schnell ermittelt werden, ob ein Datensatz mit den Suchkriterien existiert. Der IndexName bestimmt dabei die Sortierung, über die KeyValues können dann die Sortierungsfelder angesprochen werden. Bei genau einem Suchkriterium kann dieses direkt angegeben werden. Mehrere Suchkriterien übergibt man in einem Varianten-Array. Die Reihenfolge der Suchkriterien müssen der Reihenfolge der Sortierungsfelder entsprechen. Es darf dabei kein Sortierungsfeld ausgelassen oder übersprungen werden (d.h. es muss mit dem 1. Sortierungsfeld begonnen werden).
Siehe auch: SetKey, GotoKey.
Beispiele:
a) [Artikel-AutoDataSet].FindKey('Nr', '12345') sucht den Artikel mit der Nummer 12345. Wenn gefunden, erhält man im Rückgabewert den Wert TRUE und der Artikel-AutoDataSet wurde auf den Artikel-Datensatz 12345 positioniert. Wenn der Datensatz nicht gefunden wird, erhält man FALSE.
b) [Artikel-AutoDataSet].FindKey('RefWert', [Varianten-Array mit den Inhalten 'Computer' und '3']) sucht den Artikel mit der Referenz Computer und dem Referenzwert 3. Wenn gefunden, erhält man im Rückgabewert den Wert TRUE und der Artikel-AutoDataSet wurde auf den Artikel-Datensatz positioniert. Wenn der Datensatz nicht gefunden wird, erhält man FALSE.
Parameter
| Parameter | Beschreibung |
|---|---|
| [in] BSTR IndexName | Name des Index |
| [in] VARIANT KeyValues | Ein einzelnes Suchkriterium übergibt man als String. Mehrere Suchkriterien übergibt man in einem Varianten-Array |
| [out, retval] VARIANT_BOOL* Result | Boolean: "True", wenn der Datensatz gefunden wurde, ansonsten "False" |
IAutoDataSet13::SetRange Methode
Setzt einen Range auf die Tabelle.
IDL
[id(0x000005E3)]
HRESULT _stdcall SetRange([in] BSTR IndexName, [in] VARIANT StartValues, [in] VARIANT EndValues, [out, retval] VARIANT_BOOL* Result);
Beschreibung
Über diese Funktion kann eine Tabelle auf einen Bereich eingegrenzt werden. Der IndexName bestimmt dabei die Sortierung, über die Start- und EndValues können dann die Sortierungsfelder für die Bereichseinschränkung angesprochen werden. Bei genau einem Wert für die Bereichseinschränkung kann dieses direkt angegeben werden, mehrere Kriterien übergibt man in einem Varianten-Array. Die Reihenfolge der Kriterien müssen der Reihenfolge der Sortierungsfelder entsprechen. Es darf dabei kein Sortierungsfeld ausgelassen oder übersprungen werden (d.h. es muss mit dem 1. Sortierungsfeld begonnen werden).
Siehe auch: SetRangeStart, SetRangeEnd, ApplyRange.
Beispiele:
a) [Artikel-AutoDataSet].SetRange('Nr', '1', '1Z') grenzt die Artikel auf den Bereich "alle Artikel, die mit einer 1 anfangen" ein. Wenn der Bereich mindestens einen Artikel umfasst, erhält man im Rückgabewert den Wert TRUE und der Artikel-AutoDataSet wird auf dem ersten Artikel-Datensatz positioniert. Wenn kein Datensatz im Bereich verfügbar ist, erhält man FALSE.
b) [Artikel-AutoDataSet].SetRange('NrNum', '1000', '9999') grenzt die Artikel auf den Bereich zwischen der Nummer numerisch 1000 und 9999 ein.
c) [Vorgang-AutoDataSet].SetRange('Dat', '01.01.2017', [Null]) grenzt die Vorgänge auf den Bereich ab dem 1.1.2017 ein. Null definiert einen Variante mit dem Inhalt Null. Null bedeutet einen offenen Bereich, d.h. der Bereich ist am Ende nicht beschränkt.
Parameter
| Parameter | Beschreibung |
|---|---|
| [in] BSTR IndexName | Name des Index |
| [in] VARIANT StartValues | Startwert(e) für den Range. Ein einzelnes Kriterium als String, mehrere als Varianten-Array |
| [in] VARIANT EndValues | Endwert(e) für den Range. Ein einzelnes Kriterium als String, mehrere als Varianten-Array. Null für einen offenen Bereich |
| [out, retval] VARIANT_BOOL* Result | "True", wenn der Bereich mindestens einen Datensatz enthält |
3.1.39 IAutoDataSet14 Interface
Von IAutoDataSet13 abstammendes Interface.
IDL
[ uuid(6CEBD10F-8541-4B83-9CC6-D3CE87FE62F9), version(1.0), dual, oleautomation ]
interface IAutoDataSet14 : IAutoDataSet13;
IAutoDataSet14 Eigenschaften
Die folgende Tabelle zeigt die Eigenschaften von IAutoDataSet14.
Methoden
| Name | Beschreibung |
|---|---|
| Alle Methoden aus IAutoDataSet13 |
Eigenschaften
| Name | Beschreibung |
|---|---|
| Alle Eigenschaften aus IAutoDataSet13 | |
| Backward | Kehrt die Sortierreihenfolge der Tabelle um. |
IAutoDataSet14::Backward Eigenschaft
Kehrt die Sortierreihenfolge der Tabelle um.
IDL
__property VARIANT_BOOL Backward;
Beschreibung
Schaltet man Backward auf TRUE, wird die Sortierung der Tabelle umgekehrt.