Science makes it known,
Engineering makes it work,
Art makes it beautiful.
D program calling XBLite Library
This page discusses developing D main programs (also applies to D .dll)
calling functions in a XBLite dynamic link Library (.dll). In this
example, the D main program initializes the XBLite .dll, then calls four
functions to calculate an ellipse perimeter.
- use
extern (C) {...}1 to declare the external XBLite functions,
their return data type, and their passed arguments' data types (specifying
passed arguments' names is optional, can be omitted; included in the
example below) in the D calling program; arguments are passed in normal
order;
- use DECLARE CFUNCTION for the corresponding functions in
the XBLite Library;
- recommend only pass arguments from D to XBLite by value.2
Sample D Code
Below is a listing of the D command console main program (dellips.d - developed on an AMD Athlon II running WinXP Pro SP3 using
import std.stdio;
import core.runtime;
// implib /system ellps125.lib ellps125.dll
// /system Prepend '_' to exported internal names (NT system DLL)
extern (C)
{
int xbEntry2c () nothrow;
float XBgauskumc (float a, float b) nothrow;
float XBgkcc (float a, float b) nothrow;
float XBeulerc (float a, float b) nothrow;
float XBmaclaurinc (float a, float b) nothrow;
}
int main(string[] args)
{
float a, b, p;
int i;
printf(" \n");
try
{
Runtime.initialize;
}
catch (Throwable e)
{
printf(" dellips - threw initialize error");
return (0);
}
// ----- ----- ----- ----- -----
i = xbEntry2c ();
printf(" xbEntry2c result %d \n", i);
a = 20.0;
b = 10.0;
p = XBgauskumc (a, b);
printf(" %f, %f, %f \n", a, b, p);
p = XBgkcc (a, b);
printf(" %f, %f, %f \n", a, b, p);
printf(" \n");
// ----- ----- ----- ----- -----
try
{
Runtime.terminate;
}
catch (Throwable e)
{
return (0);
}
return (0);
}
XBLite Library
ELLPS125.X is a port from Microsoft EXCEL Visual Basic to XBLite of several ellipse perimeter functions3. Used the same approach as in the USPS Address Matching System Application Programming Interface (AMS API) (see Using Fujitsu COBOL 3.0 to call the USPS AMS API) - two declarations for each function, each with a different LinkageType.1 The first is the XBLite "default protocol" from DECLARE FUNCTION, the second is DECLARE CFUNCTION.4 The D program calls the CFUNCTION, the CFUNCTION calls the FUNCTION. The FUNCTION subprograms have been successfully called by a XBLite Windows program.
The CFUNCTION has the same name as the FUNCTION with a 'c' appended. Developed on a Dell Optiplex GX150 running WinXP Pro SP2.
- Available CFUNCTIONs
-
xbEntry2c ( )
calls / returns xbEntry2 ( ), initializes the standard function library; required -
SINGLE XBhgsc (SINGLE a, SINGLE b, SINGLE c, SINGLE z)
calls / returns SINGLE XBhgs (SINGLE a, SINGLE b, SINGLE c, SINGLE z)
Hypergeometric function y = F(α, β; γ; z);
solution to the differential equation
z(1 - z)y´´ + [γ - (α + β - 1)z]y´ - αβy = 0
As an example when |z| < 1, defined by power series
F(α, β; γ; z) = ∑n=0∞ ( (αn βn) / γn) (zn / n!)
other conditions (γ < 0, |z| => 1, etc.) require different equations
XBhgs (...) is called by XBeuler (...) and XBmaclaurin (...) -
SINGLE XBgauskumc (SINGLE a, SINGLE b)
calls / returns SINGLE XBgauskum (SINGLE a, SINGLE b); Gauss-Kummer relation to calculate perimeter of ellipse -
SINGLE XBcayleyc (SINGLE a, SINGLE b)
calls / returns SINGLE XBcayley (SINGLE a, SINGLE b); Cayley series to calculate perimeter of ellipse -
SINGLE XBgkcc (SINGLE a, SINGLE b)
calls / returns SINGLE XBgkc (SINGLE a, SINGLE b); Gauss-Kummer relation or Cayley series;
XBgkc (...) calls either XBgauskum (...) or XBcayley (...) depending on b / a (rough inverse approximation of eccentricity) to calculate perimeter of ellipse -
SINGLE XBeulerc (SINGLE a, SINGLE b)
calls / returns SINGLE XBeuler (SINGLE a, SINGLE b); Euler Formula to calculate perimeter of ellipse -
SINGLE XBmaclaurinc (SINGLE a, SINGLE b)
calls / returns SINGLE XBmaclaurin (SINGLE a, SINGLE b); Maclaurin series expansion to calculate perimeter of ellipse
Compiling and Linking
-
ELLPS125.X
Two Step Process
Step 1:
Within XSED, click on
Run
Compile as Library (DLL)
Only use
Build
when creating an .exe file
Step 2:
Two of the files generated by XSED/XBLite during "compilation" areELLPS125.asm andELLPS125.bat.
Execute ELLPS125.bat in a Command Prompt to assemble and linkELLPS125.asm intoELLPS125.dll .
ELLPS125.dll is the only file required from this step.
-
dellips.d
To execute dellips.exe, simply type dellips in a command prompt.
First, in a D2 32-bit Command Prompt use DMD utility implib to build a DMD compatibleELLPS125.lib , as shown at right (the .lib file created above by Microsoft Linker is not compatible). Use the /system switch to prepend '_' to exported internal names (NT system DLL), required by D for external C subprograms.
Next, use the dmd compiler to compile dellips.d, as shown at right. Theellps125.lib argument links in the XBLite functions.
1. "If the library was created from a C program, then it will probably be compatible with XBLite." - XBLite documentation
In the D statement extern (C) {...}, C is the LinkageType. Other available D LinkageTypes are: Pascal, C++, D, Windows, and System. Judging by the compiler behavior, using these other LinkageTypes (with the exception of Pascal - see Pascal calling D and FORTRAN footnotes) seems to cause some sort of name mangling. Pascal LinkageType requires passing the arguments in reverse order.
2. Without any changes whatsoever to the called subprogram, in an all XBLite application arguments may be passed by value, by reference, or by address (pointer) by the calling program. Another example, SSHORT (short in D) variables are stored as SLONG (int in D) internally. XBLite's "default protocol" does not seem supportive of being called by non-XBLite programs passing arguments by reference/address.
3. Chandrupatla, Tirupathi R., and Thomas J. Osler (2010). The Perimeter Of An Ellipse Mathematical Scientist.
Review / comparison of four ellipse perimeter calculation methods. Elliptical area / perimeter calculations can be complex, involving geometric angles, parametric angles, integrations.
4. "CDECL protocol" - declares/defines C functions or C callable functions.
