define_external(..., LIB=libName) - connect to an external wrapper shared library
|
Calling Sequence
|
|
define_external(..., LIB=libName)
|
|
Parameters
|
|
libName
|
-
|
name of external library containing the function
|
|
|
|
|
Description
|
|
•
|
Before any C or Fortran function can be used with define_external, it must first be compiled into a shared library. Java functions must be compiled into .class files.
|
•
|
A shared library is also known as a dynamic link library (DLL). Typically the .dll extension is used on Windows, lib*.so is used on most versions of UNIX (other variations are lib*.sl and lib*.a). One Mac convention uses the .dylib extension.
|
•
|
If the sources are downloaded from the internet or purchased, a DLL may already have been built. Otherwise, consult the compiler's documentation for help on how to build a DLL.
|
•
|
For Maple the external library functions must be compiled using the __stdcall calling convention. This is the one and only convention used by UNIX shared libraries. Windows C compilers can use any one of three conventions, __cdecl, __fastcall, or __stdcall. Maple only recognizes functions compiled with __stdcall. The Microsoft Visual C/C++ compiler allows you to specify this convention globally (on all functions) with the flag /Gz. Individual functions can be declared to use this convention by inserting the word __stdcall between the return type and function name.
|
•
|
When building the DLL, ensure that you export the function that Maple is intended to be able to call. Functions that are not exported cannot be accessed.
|
•
|
Some compilers will export, or make public, all functions in your program. This means programs using the shared library can find all functions in order to make use of them. Other compilers need explicit decorations on the function declaration, and/or a file that lists all the functions that should be exported. The MSVC compiler can export functions in a variety of ways. Exports can be listed in a .def file. The name __declspec(dllexport) can be inserted before the return type in the functions declaration. The /export:name compiler command-line option can be used.
|
•
|
Using the Sun Workshop C/C++ compiler on Solaris, the -G option creates a shared library. For example, the following command line creates libtest.so.
|
|
cc -G test.c -o libtest.so
|
•
|
Microsoft Visual C/C++ on Windows uses -LD (or -link -dll) to create a dll. It needs -Gz to use standard calling convention. It also uses -export:name to declare which functions are to be exported. The following MSVC command line creates test.dll.
|
|
cl test.c -Gz -LD -link -export:myfunc
|
•
|
To use the MSVC command line, you need to set the %LIB% and %INCLUDE% environment variables. Running vcvars32.bat will do this for you.
|
•
|
Using the GNU gcc C compiler on Linux, the -shared option creates a shared library. For example, the following command line creates libtest.so.
|
|
gcc -shared test.c -olibtest.so
|
•
|
Fortran compilers use several different calling conventions. Fortran external call has been tested only with the GNU g77 compiler on various platforms. There are known incompatibilities with other compilers, especially when using string arguments. Try to get a simple example working before moving to a more complicated one. Test to ensure your Fortran compiler uses compatible calling conventions.
|
•
|
To call Java functions, jvm.dll needs to be in your PATH. You may need to install a Java Developer's Kit (JDK) to get this dll. UNIX installations need at least libjvm.so and libhpi.so in the PATH. Typically the following directories need to be added to your PATH.
|
OS
|
PATH
|
Windows
|
$JAVA/jre/bin/classic;$JAVA/jre/bin
|
Solaris
|
$JAVA/jre/lib/sparc:$JAVA/jre/lib/sparc/native_threads
|
Linux
|
$JAVA/jre/lib/i386/classic:$JAVA/jre/lib/i386/native_threads:
|
|
$JAVA/jre/lib/i386
|
|
|
|
Note (Mac OS X): No path needs to be added for Mac OS X. By default, it exists on all Macintosh systems.
|
•
|
The above paths may differ depending on the version and supplier of the JDK you install. $JAVA is the base directory where the JDK was installed.
|
|
|
Download Help Document
Was this information helpful?