Xsub

---

External Subroutine Call

The Xsub function calls an external subroutine inside a DLL file. Xsub is perhaps the most powerful statement in ProModel, because you can access the entire functionality of any 32-bit Windows programming language such as C, C++, Delphi, or Visual Basic. Xsub can be used for sophisticated file IO and to make simulations interactive. In fact, subroutines called with Xsub can do anything that the language they were written in allows. Because of its power, however, Xsub should be used with caution. When called, the simulation is suspended until the external subroutine finishes execution.

The subroutine inside the DLL must be compiled as exportable by a Windows 32-bit compiler and have a return type of IEEE format double real. Xsub copies the parameters following the function name to a block of memory, then pass the function a pointer to that block of memory.

The function can take only one parameter: a pointer to void. But the function may access any number of parameters through structure overlaying. The function should define a structure to match the parameters' type and order, and assign the pointer just passed to a pointer to that type of structure. The parameters can then be used through structure overlaying. Integers are passed as four byte values and reals are passed as eight byte IEEE values.

Syntax

Xsub(<file ID>, <ordinal function number> or <function name> {, <parameter1>, <parameter2>...})

Syntax Examples

Xsub(Interface,1, 5)

Xsub(LogDLL, "_Log_B_of_X",10,5)

Parameters

<file ID>

The file ID assigned to an external DLL file as defined in the External Files Editor. This file should be a 32-bit Windows DLL file.

<ordinal function number>

Represents the function's ordinal number inside the DLL. This function must be exportable. When DLL's are compiled, every exported function inside them is numbered. The individual functions can then be accessed by calling the program by number. This field may be an expression that evaluates to an ordinal function number that is valid inside the DLL. Use an ordinal function number or the function name.

<function name>

Represents the name of the function inside the DLL. This function must be exportable. Note that when most compilers process DLL's, they adjust the name of the functions inside them. The function name inside the Xsub statement must be the adjusted name, not the original name. Most C compilers add an underscore to the function name; so a function called "Test1" would be compiled as "_Test1". For most C++ compilers, valid ProModel external function names are mangled to "@<function name>$pv." Different compilers vary, however, so be aware of the particular compiler's quirks.

<parameter>

The parameter fields should be the parameters to pass to the function. These may be any Variable, number, or expression. They are only limited by the field or logic type that uses the Xsub function. Each parameter should be separated by a comma. See previous for how the external subroutine accesses these parameters.

Remarks

For Windows Programmers Only - The handle to the run-time simulation frame window is the last parameter passed. Most subroutines can completely ignore this parameter, but it is needed if the subroutine displays a window.