EBSILON®Professional Online Documentation
The open software architecture of EBSILON®Professional enables a simple access to EBSILON®Professional data by programs.
This chapter describes the DLL called "TheUsersDLL.dll" that is used for data exchange. There is another DLL interface (Programmable.dll) to define own components for the calculation kernel.
The User DLL can be used for data export and import.
Note:
As some structures have changed (e.g. LINERESULTS), it is recommended to newly generate self-provided DLLs with the header files of Release 10.
With your EBSILON®Professional CD, a sample DLL was shipped. You can find the source code for this example in Examples\DLL_Interfaces. There are two files that were used to create the example "TheUsersDLL.dll":
These files were compiled and linked to a DLL with the Microsoft Developer Studio 6.0. The resulting DLL is placed in the installation directory of EBSILON®Professional.
The file "userDll.h” defines the DLL interface. You should include this file in your application.
Note that this interface may be extended in future EBSILON®Professional versions. Therefore be careful to rebuild your application with the latest version of the header file when you are going to use a new EBSILON®Professional version.
The file "userDll.c” is the source code file that you can modify according to your needs.
In the first step, you should try to rebuild this DLL. Set up your own project and create a DLL called "TheUsersDLL.dll" using the source code from userDll.c. Copy this DLL to the directory where EBSILON®Professional was installed and try to call this DLL from EBSILON®Professional.
If the sample DLL you have created shows the same behaviour as our original DLL, you can turn to the next step and modify the source code.
Do not modify "userDll.h”, as this file must match with the "userDll.h” that we used when we generated the EBSILON®Professional executable.
The DLL interface is described in the header file "userDll.h". It is assumed that you write your program in C or C++. Generally, it should be possible to use another programming language as well. In this case, you have to be careful for the correct interpretation of the transferred data.
The DLL interface consists of a single function called "EbsUserDLL" that returns an integer value. You may specify this return value as you like. The return value will be
The only argument of the function "EbsUserDLL" is a pointer to a EBS_USER_DATA structure.
This structure is defined as
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;
Before EBSILON®Professional calls your DLL, it creates this structure and copies the data from the active profile into this structure. Therefore, in your DLL you have access to all these data in the structure.
Look at the function "example1 ()" in userDll.c to see how you can access EBSILON®Professional specification values, results, characteristic lines and other parameters.
The EBS_USER_CALL_PARAMS are specified either in the DLL dialog or as EbsScript arguments. You can use these calling parameters to determine a different behaviour of your DLL depending on this parameters. You have an integer parameter called nProgId, four additional integer parameters, four real parameters and four string parameters. For details of the structure see userDll.h.
In the example DLL, nProgId is used to switch between three different functions.
Example1 is a simple ASCII output of all EBSILON®Professional data. The string parameter szParam1 is used to specify the path name of the file that shall be created (of course, you can use this as a report function even if you do not want to create your own DLL).
The EBS_USER_INTERFACE_CONTROL structure consists of a flag to determine if EBSILON®Professional shall read back data from your DLL (see DLL Import). If you only want to receive data from EBSILON®Professional leave this flag 0.
The EBS_USER_CALCCONTROL_PARAMS are the calculation settings that were specified on "ExtrasàModel Options" on the sheets "Simulation", "Validation", "Results" and "User-Defined Fluids". User-defined variables are not included in this interface yet.
The EBS_USER_LINEDATA is an array of nlines entries, one for each line in the cycle. Each entry consists of several substructures:
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 consists of the id, the name and description of the line. The EBS_USER_LINETYPE indicates the type of line (the fluid type). The EBS_USER_LINERESULTS contain the calculated thermodynamical properties of the line (pressure, temperature, &ldots;, also the material composition). The EBS_USER_LINETOPO structure indicates the topology: it may point to a component, a line (in case of a logical line) or to nothing. topo[0] and topo[1] contain the topology of both line endings.
The EBS_USER_COMPDATA is an array of ncomps entries, one for each component in the cycle. Each entry consists of several substructures:
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 consists of the id, the name and description of the component. The comptype is the number for the component type. The EBS_USER_COMPTOPO structure may point to a line or to nothing. The array pins consists of npins EBS_USER_COMPTOPO entries that indicate which line is connected at the corresponding connection point (if any).
The EBS_USER_SPECITEMstructure contains the name and the value of a specification or result value::
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;
Depending on the valuetype, the value is a double or a long value. If the specification value is empty, the flag bempty is set to 1 (TRUE). In this case, you shall not use doublevalue or longvalue (they may have arbitrary values). The writeback flag is used in case of data import only.
The arrays specs and results consist of nspecs and nresults of such entries.
The EBS_USER_CHARLINEstructure contains data of a characteristic line.
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;
If the flag buseparam is 1 (TRUE), the characteristic line has a parameter that is indicated in param. If buseparam is 0 (FALSE), the value of param is arbitrary and shall not be used. The array points contains the npoints points of the characteristic line. The writeback flag is used in case of data import only.
The array charlines in the EBS_USER_COMPDATAstructure consists of ncharlines of such entries.
For component that do not have connection points but are placed directly on the line (component 33, 45, 46), the topology is indicated in logiccomp. This is a EBS_USER_COMPTOPOstructure that points to the line where the component is located on. The flag blogiccomp indicates whether this value is used (=1) or not (=0). If blogiccomp is 0, you shall not use logiccomp.
If you want to export calculated data from EBSILON®Professional to your DLL, you must do a calculation in the actual profile before calling the DLL.
To call the DLL, use the menu command DataàUser DLLàCall&ldots;”. The "Call User-DLL" dialog is opened.
In this dialog, you may specify parameters that are transferred to your DLL in addition to the EBSILON®Professional data. It is not necessary to specify any parameters if you do not want to use them in your DLL.
In this example, the program id nProgID = 1 expects one string argument which is specified here. It is the path name of the printout file for this example program.
When you have finished specifying the parameters, click "Call Dll&ldots;". Your DLL is called now.
Thereafter, the field "Result" on the upper right corner indicates the return code of your DLL.
You can now change the parameters and perform another call to your DLL, or close the dialog window.
Alternatively, it is possible to call the DLL from an EbsScript. See EbsScript functions.