EBSILON®Professional Online Dokumentation
Die offene Software Architektur von Ebsilon erlaubt einen einfachen Zugriff auf Ebsilon Daten durch andere Programme.
Dieses Kapitel beschreibt die DLL mit dem Namen ”TheUsersDLL.dll”, die für den fDatenaustausch verwendet wird. Es gibt eine andere DLL Schnittstelle (Programmable.dll) um eigene Komponenten für den Rechenkern zu definieren.
Die Benutzer DLL kann für Datenexport und - import verwendet werden.
Um diese Schnittstelle zu benutzen, müssen Sie
Anmerkung
Da sich einige Strukturen geändert haben (z.B. LINERESULTS), empfiehlt es sich, selbst erstellte DLLs mit den Header-Dateien der Release 10 neu zu generieren.
Mit Ihrer EBSILON®Professional CD wurde ein DLL Beispiel ausgeliefert. Sie können den Quellcode für dieses Beispiel in Examples\DLL_Interfaces finden. Dort gibt es zwei Dateien, die dazu verwendet wurden, das Beispiel ”TheUsersDLL.dll” zu erstellen:
Diese Dateien wurden mit dem Microsoft Developer Studio 6.0 kompiliert und mit einer DLL verkettet. Die sich daraus ergebende DLL ist in das Ebsilon Installationsverzeichnis platziert worden.
Die Datei ”userDll.h” definiert die DLL Schnittstelle. Sie sollten diese Datei in Ihre Applikation einbeziehen.
Beachten Sie, dass diese Schnittstelle in künftigen EBSILON®Professional Versionen erweitert werden kann. Seien Sie deshalb vorsichtig beim Wiederaufbauen Ihrer Applikation mit der letzen Version der Headerdatei, wenn Sie im Begriff sind, eine neue Ebsilon Version zu verwenden.
Die Datei ”userDll.c” ist die Quellcodedatei, die Sie gemäß Ihren Wünschen modifizieren können.
Im ersten Schritt sollten Sie versuchen, diese DLL wiederaufzubauen. Setzen Sie Ihr eigenes Projekt auf und erstellen Sie eine DLL mit dem Namen ”TheUsersDLL.dll” unter Verwendung des Quellcodes aus userDll.c. Kopieren Sie diese DLL in das Verzeichnis, in das Ebsilon installiert wurde, und versuchen Sie, diese DLL aus Ebsilon heraus aufzurufen.
Wenn das von Ihnen selbst erstellte DLL-Beispiel dasselbe Verhalten zeigt wie die von uns gelieferte Original-DLL, können Sie zum nächsten Schritt übergehen und den Quellcode modifizieren.
Modifizieren Sie nicht ”userDll.h”, da diese Datei zu ”userDll.h”, passen muss, die wir benutzten, als wir die Ebsilon Lauffähigkeit generierten.
Die DLL Schnittstelle ist in der Headerdatei ”userDll.h” beschrieben. Es wird angenommen, dass Sie Ihr Programm in C oder C++ schreiben. Im allgemeinen sollte es möglich sein, ebenso gut eine andere Programmiersprache verwenden zu können. In diesem Falle müssen Sie auf die korrekte Auslegung der transferierten Daten achten.
Die DLL Schnittstelle besteht aus einer einzigen Funktion mit dem Namen ”EbsUserDLL”, die einen Integer Wert zurückgibt. Sie können diesen Rückgabewert beliebig spezifizieren. Der Rückgabewert wird
Das einzige Argument der Funktion ”EbsUserDLL” ist ein Zeiger zur EBS_USER_DATA Struktur.
Diese Struktur ist definiert als
typedef struct {
EBS_USER_CALL_PARAMS callparams; // calling parameters
EBS_USER_INTERFACE_CONTROL control; // interface controlling parameters
EBS_USER_CALCCONTROL_PARAMS params; // calculation controlling parameters
int nlines; // number of lines
EBS_USER_LINEDATA *lines; // lines
int ncomps; // number of components
EBS_USER_COMPDATA *comps; // components
} EBS_USER_DATA;
Bevor EBSILON®Professional Ihre DLL aufruft, erstellt es diese Struktur und kopiert die Daten aus dem aktuellen Profil in diese Struktur.
Sehen Sie nach der Funktion ”example1 ()” in userDll.c, um zu sehen, wie Sie EBSILON®Professional Spezifikationswerte, Ergebnisse, Kennlinien und andere Parameter aufrufen können
Die EBS_USER_CALL_PARAMS sind entweder im DLL Dialog oder als EbsScript Argumente spezifiziert. Sie können diese Aufrufparameter dazu verwenden, ein unterschiedliches Verhalten Ihrer DLL in Abhängigkeit dieser Parameter zu bestimmen. Sie haben einen Integer Parameter mit dem Namen nProgld, vier zusätzliche Integer Parameter, vier reale Parameter und vier Folge Parameter. Für Details der Struktur sehen Sie userDll.h.
Im Beispiel DLL wird nProgld dazu verwendet, zwischen drei verschiedenen Funktionen umzuschalten.
Beispiel 1 ist eine einfache ASCII Ausgabe aller Ebsilon Daten. Der Folge-Parameter szParam1 wird dazu verwendet, den Pfadnamen der Datei zu spezifizieren, die erstellt werden soll (natürlich können Sie dies als eine Bericht Funktion verwenden, auch wenn Sie nicht Ihre eigene DLL erstellen möchten).
Die EBS_USER_INTERFACE_CONTROL Struktur besteht aus einem Flag, um festzulegen, ob Ebsilon Daten aus Ihrer DLL zurücklesen soll (siehe DLL Import). Wenn Sie nur Daten aus Ebsilon erhalten möchten, belassen Sie dieses Flag bei 0.
Die EBS_USER_CALCCONTROL_PARAMS sind die Berechnungseinstellungen, die spezifiziert wurden nach ”ExtrasàModell Optionen” in den Blättern ”Simulation”, ”Validierung”, ”Ergebnisse” und ”Benutzerdefinierte Flüssigkeiten”. Benutzerdefinierte Variablen sind in dieser Schnittstelle noch nicht vorhanden.
Die EBS_USER_LINEDATA ist eine Reihe von nlines Einträgen, einen für jede Zeile im Kreislauf. Jeder Eintrag besteht aus verschiedenen Unterstrukturen:
typedef struct tagEBS_USER_LINEDATA{
EBS_USER_BASICS basics; // Basic Parameters
EBS_USER_LINETYPE type; // Line Type
EBS_USER_LINERESULTS results; // Line Results
EBS_USER_LINETOPO topo[2]; // Topology
} EBS_USER_LINEDATA;
EBS_USER_BASICS besteht aus der ID, dem Namen und der Beschreibung der Zeile. Der EBS_USER_LINETYPE weist auf den Zeilentyp hin (Flüssigkeitstyp). Die EBS_USER_LINERESULTS enthalten die berechneten thermodynamischen Eigenschaften der Zeile (Druck, Temperatur, ..., auch die materielle Struktur). The EBS_USER_LINETOPO Struktur weist auf die Topologie hin: Sie kann auf eine Komponente, eine Zeile (im Falle einer logischen Zeile) oder auf nichts hindeuten. topo[0] and topo[1] enthält die Topologie beider Zeilenenden.
Die EBS_USER_COMPDATA ist eine Reihe von ncomps Einträgen, einer für jede Komponente im Kreislauf. Jeder Eintrag besteht aus verschiedenen Unterstrukturen:
typedef struct tagEBS_USER_COMPDATA{
EBS_USER_BASICS basics; // Basic Parameters
int comptype; // component type
int npins; // number of connection points
EBS_USER_COMPTOPO *pins; // Array (npins elements) with topology info
int nspecs; // number of specification values
EBS_USER_SPECITEM *specs; // specification values
int nresults; // number of result values
EBS_USER_SPECITEM *results; // result values
int ncharlines; // number of characteristic lines
EBS_USER_CHARLINE *charlines; // Array (ncharlines elements) with characteristic lines
int blogiccomp; // flag (TRUE, if logiccomp is used)
EBS_USER_COMPTOPO logiccomp; // topology info for a logical component
} EBS_USER_COMPDATA;
EBS_USER_BASICS besteht aus der ID, dem Namen und der Beschreibung der Komponente. Die comptype ist die Nummer für den Komponententyp. Die EBS_USER_COMPTOPO Struktur kann auf eine Zeile oder auf nichts hindeuten. Die Reihe pins besteht aus npins EBS_USER_COMPTOPO Einträgen, die darauf hindeuten, welche Linie mit dem entsprechenden Verbindungspunkt verbunden ist (wenn überhaupt eine).
Die EBS_USER_SPECITEM Struktur enthält den Namen und den Wert eines Spezifikations- oder Ergebniswertes:
typedef struct {
char *name; // short name of the specification value
EBS_USER_VALUETYPE valuetype; // flag whether value is double or long
union {
double doublevalue;// value as double
long longvalue; // value as long
};
int bempty; // flag: = 1, if value is empty
EBS_USER_WRITEBACK writeback; // flag for writeback
} EBS_USER_SPECITEM;
Abhängig vom valuetype ist der Wert ein double oder ein long Wert. Wenn der Spezifikationswert leer ist, ist das Flag bempty auf 1 (TRUE) gesetzt. In diesem Falle sollten Sie keine double oder long Werte verwenden (sie können unbestimmte Werte haben). Das writeback Flag wird nur im Falle von Daten Import verwendet.
Die Reihen specs und results bestehen aus nspecs und nresults solcher Einträge.
Die EBS_USER_CHARLINE Struktur enthält Daten einer Kennlinie.
typedef struct {
char *name; // Name of the characteristic line
int buseparam; // Flag whether the characteristic has a parameter
double param; // Parameter
int npoints; // Number of points
EBS_USER_CHARLPOINT *point; // Array (npoints elements) of points
EBS_USER_WRITEBACK writeback; // Flag for writeback
} EBS_USER_CHARLINE;
Wenn das Flag buseparam 1 (TRUE) ist, hat die Kennlinie einen Parameter, auf den in param hingewiesen wird. Wenn buseparam 0 (FALSE) ist, ist der Wert von param beliebig und sollte nicht verwendet werden. Die Reihe points enthält die npoints Punkte der Kennlinie. Das writeback Flag wird nur im Falle von Daten Import benutzt.
Die Reihe charlines in der EBS_USER_COMPDATA Struktur besteht aus ncharlines solcher Einträge.
Für Komponenten, die keine Verbindungspunkte haben, aber direkt auf der Linie platziert sind (Komponente 33, 45, 46), wird die Topologie in logiccomp angezeigt. Dies ist eine EBS_USER_COMPTOPO Struktur, die auf die Linie hindeutet, auf der die Komponente lokalisiert ist. Das Flag blogiccomp zeigt an, ob dieser Wert verwendet wird (=1) oder nicht (=0). Wenn blogiccomp 0 ist, sollten Sie logiccomp nicht benutzen.
Wenn Sie berechnete Daten aus Ebsilon in Ihre DLL exportieren möchten, müssen Sie eine Berechnung im aktuellen Profil durchführen, bevor Sie die DLL aufrufen.
Um die DLL aufzurufen, verwenden Sie den Menübefehl ”DatenàUser DLLàAufrufen...”. Der ”Benutzer-DLL aufrufen” Dialog wird geöffnet
In diesem Dialog können Sie Parameter spezifizieren, die ergänzend zu Ihren EBSILON®Professional Daten in Ihre DLL transferiert werden. Es ist nicht notwendig, Parameter zu spezifizieren, wenn Sie sie in Ihrer DLL nicht verwenden möchten.
In diesem Beispiel erwartet das Programm id nProgID = 1 ein Folge Argument, das hier spezifiziert wird. Es ist der Pfadname der Protokolldatei für dieses Beispielprogramm.
Wenn Sie die Spezifizierung der Parameter abgeschlossen haben, klicken Sie ”Call Dll...”. Ihre DLL wird nun aufgerufen.
Danach zeigt das Feld ”Ergebnis” in der oberen rechten Ecke den Rückgabe Code Ihrer DLL an.
Nun können Sie die Parameter ändern und einen neuen Aufruf an Ihre DLL durchführen oder das Dialogfenster schließen.
Alternativ ist es möglich, die DLL aus einem EbsScript heraus aufzurufen. Mehr dazu siehe in See EbsScript Funktionen.