Foreign Language Interface Example

Modified Bessel of the First Kind

readme.txt
ribesl.dll - Windows 95 .dll
ribesl.c - source code
myf2c.h - header file
ribesl.src
bessel.e - example run
ribesl.zip - compressed file containing all of the above files

The procs in ribesl.src compute modified bessel functions of the first kind, and of any order. They may be used immediately by copying
```
     ribesl.src  to  GAUSSDIR/src
     ribesl.dll  to  GAUSSDIR/dlib
```
then enter
```
     dlib_path = $(GAUSSDIR)\dlib
```
into your gauss.cfg file which is in the GAUSSDIR directory.
Next, from GAUSS enter
```
     lib -a user ribesl.src
```
which will add the procs in ribesl.src to your user library.
Then copy bessel.e to a directory and run it.
Also contained in the .zip file are the source code files for creating your own .dll. This example illustrates the various phases of getting source code into a GAUSS function. It's divided into the following parts:

I Finding source code

II Translating Fortran into C

III The wrapper function

IV Compiling into a .dll

V Using the .dll in GAUSS

VI The .SRC file

I Finding the Source Code
You may have code already, or you may have written your own function in Fortran or C. If it's Fortran and you don't have a Fortran compiler go to step II. If you have a Fortran compiler, or it's in C and you have a C compiler, go to Step III. Otherwise, you may need to look for code.
The best place to look is Netlib. Go to the URL
http://www.netlib.org
There's a search engine there as well as a browser. An index of free C/C++ code for numerical computation may be found at
ftp://ftp.math.psu.edu/pub/FAQ/numcomp-free-c
The example presented here computes the modified Bessel of the first kind. I searched Netlib and found the RIBESL function which computes a modified Bessel of the first kind across a sequence of orders.

II Translating the Fortran into C
I have a C compiler on my Windows 95 machine (i.e., Symantec C++). The source code is in Fortran (as is most numerics software), however, and I don't have a Fortran compiler. This isn't a serious problem, though, because of Netlib's f2c program which translates a Fortran program into ANSI C. Anyone can use Netlib's f2c program. Simply put the Fortran code into the body of an e-mail message, enter
```
   execute f2c
```
in the subject line, and e-mail to
```
   netlib@research.att.com
```
The C translation will come back as an e-mail message.
The f2c-ed source code requires an f2c.h, and some functions located in libf77. These files contain some defines and functions that are needed by the f2c-ed source code. f2c.h and libf77 may be found at
http://www.netlib.org/f2c/f2c.h
http://www.netlib.org/f2c/llibf77
For Fortran code that does only numerical computation, a lot of what is contained in these files isn't needed. To simplify things, I have extracted from f2c.h and libf77 only what I needed and put it into myf2c.h which accompanies this example.
If the Fortran source contains read and/or write instructions, the f2c-ed code can become quite complicated. I recommend that you remove all read/write instructions from the Fortran before f2c-ing it.

III The Wrapper Function
You will want to write a wrapper function that does the actual call to the function that does the computation. The computational function will almost always compute a single value, while you will want to compute an array of values. Also, GAUSS will only pass pointers to double arrays and strings, while the function computation may require other types. The wrapper function does all the processing of the inputs from GAUSS, including a loop over the elements of input arrays, and then calls the computational function.

IV Compiling into a .dll
Rather than a makefile, I use the Windows 95 environment for Symantec for compiling which means that the selection of features requires pulling down menus and clicking on the selections. For this example, I select compilation for Windows 95, and in another window a select .DLL for the target.
The key thing here, though, is to specify the wrapper function for "export". In my Symantec environment this took a little searching through menus to find.

V Using the .dll in GAUSS
First, GAUSS must be able to find the .dll. In the configuration file, gauss.cfg, you will need to enter a line:
```
   dlib_path = $(GAUSSDIR)\dlib
```
where dlib is a subdirectory off of GAUSSDIR. In my configuration this is d:\gauss\dlib.
Next, I put the .dll into that subdirectory.
And finally, put
```
   dlibrary xxx.dll;
```
into your startup file where xxxx.dll is your .dll file. If you have more than one .dll, enter them all in the dlibrary statement. In this way, all of the functions in your .dll are accessed in the same way that GAUSS intrinsics are accessed.

VI The .SRC file
Put the proc that calls the dll function in an .src file. This proc will contain the dllcall statement that calls the dll function. It also sets up the GAUSS arrays that are needed, and checks to make sure that the arguments in the dllcall are the correct size. The proc in the .src file will be the one you call from your GAUSS programs.
When you have finished the proc, put the .src file into the GAUSSDIR\src subdirectory. Then list the proc in your user.lcg library by entering from the GAUSS command line:
```
   lib -a user filename.src 
```
Provided you have entered information at the top of the .src file on the use of the procs in that file, the GAUSS online help system will be able to find it when the .src file is logged into your user library.
||Top||HomePage||