Lahey FORTRAN 95 DLL

GoldSim allows users to develop separate program modules (written in C, C++, Fortran or any other compatible programming language) which can then be directly coupled with the main GoldSim algorithms. This article explains how to create such an external function module using the Lahey Fortran 95 compiler. Example source code, a DLL and a model file are also available via External Function Example Using Lahey Fortran 95 Compiler in the Model Library.

In order to be able to communicate with GoldSim, external functions must always be written using the syntax specified in the GoldSim User Manuals. The following template shows the appropriate declaration of a simple function in Lahey Fortran:

 1. subroutine Sum (method, state, in, out)
 2.    dll_export Sum
 3.    integer(4), value :: method
 4.    integer(4) state
 5.    real(8) in(*), out(*), x, y
 6.   
 7.    if (method.eq.1) then !Calculate
 8.        out(1) = in(1) + in(2) !Sum
 9.    elseif (method.eq.2) then !Report version
10.        out(1) = 1.0
11.    elseif (method.eq.3) then !Report arguments
12.        out(1) = 2 !Two incoming arguments
13.        out(2) = 1 !One outgoing argument
14.    endif
15. end

The first two lines define the subroutine name and the (function) name that should be exported, which must be identical. This is the function name that is later used by GoldSim when calling the external DLL. This example uses the function name Sum.

The function arguments and the variable definitions must always be specified as shown in lines 3 to 5. They are independent from the actual meaning and purpose of your function since they define the communication between GoldSim and the external function.

When calling a function GoldSim always specifies the purpose of the call using the method variable. For instance, GoldSim assigns the value 1 to argument method to request the calculation. Depending on the value of method, the arguments in and out provide additional data or can be used to return results.

The code block in lines 7-14 shows the three method values that a function must always handle: report version, provide number of arguments, and do the calculation. Appendix C of the user manual lists all method values that GoldSim might use, and provides the details for how to use them. In this example, the function expects two incoming arguments, which will be added and returned to GoldSim.

After coding your function you should save your work in a file, for example gsfunc.f90. You can build a dynamic link library (DLL) typing the following command in the command line prompt:

lf95 gsfunc.f90 -dll

This command starts the Lahey Fortran compiler and translates the Fortran code into machine specific byte code that is stored in a DLL named gsfunc.dll.

You can check the correctness of the exported name declaration with the following command: dumpbin /exports gsfunc.dll

This command is very handy if GoldSim reports that a specified function can not be found. It allows you to see the function name as it is exported by the compiler.

You can now use the function in the DLL from within GoldSim. Simply create two new Data Definition elements representing the two incoming arguments. Call the elements A and B and give them constant values of 5 and 10.

Create an External element and add two inputs to it. Link the inputs two the outputs of elements A and B.

Then create a new output. You can use the provided defaults for data type and unit.

As the last step, you must specify the name and path of the DLL (gsfunc.dll) and the function name (Sum). You can now run the model. If you did everything correctly, the value of the external output should be 15.