This section describes the user written FORTRAN interface which allows modules in FORTRAN to be compiled and loaded into Open GENIE so that they can be run as if they had been built into the original code. Once loaded, a module can be called as efficiently as any other hard coded function from Open GENIE (see the Module() command). The function will run in a "safe" environment so that if it should crash, control will return to Open GENIE without causing a crash of Open GENIE itself.
Here we give reference information for:
For more general information and examples of using modules, see the Open GENIE User Manual
The essential purpose of this interface is to allow data transfer and communication with the running Open GENIE session from which the external FORTRAN module was called. All data transfer is handled by allowing the Module() command in GCL to take a workspace of parameters which are made available to the FORTRAN SUBROUTINEs if they adhere to a certain template. The workspace itself, is an advanced data type and as such is not easily handled itself in FORTRAN, what is provided in the FORTRAN interface is a set of Helper Functions which allow data to be read and written to and from this parameter workspace.
The FORTRAN template is actually very simple and is given below. A normal procedure for converting an existing program is to turn the program into one or more subroutines taking appropriate data as parameters and then to call these subroutines from the FORTRAN template subroutine to perform the appropriate functions. It may be necessary to separate the functional part of the program from any subroutines that query a user interactively for data, these subroutines will probably need replacing with helper functions (or they may more easily be done from GCL and/or the TK graphical interface anyway).
C An F77 template subroutine for creating an Open GENIE module in FORTRAN
C Several subroutines like the one routine below may be included in one
C module.
C
C Called from GCL with e.g. MODULE:EXECUTE("my_fortran_module", PARS)
C
C Freddie Akeroyd, ISIS, 20/2/97 - modified by CM-S 2/7/97
C
SUBROUTINE MY_FORTRAN_MODULE(PARS_GET, PARS_PUT)
IMPLICIT NONE
C Include mandatory definitions
INCLUDE 'genie_modules.inc'
EXTERNAL PARS_GET, PARS_PUT
C ... User declarations here ...
C Check we have a recent enough version of the genie library -
C all modules should do this to avoid unexpected crashes
IF (MODULE_VERSION_OK(GENIE_MAJOR, GENIE_MINOR) .EQ. 0) THEN
MODULE_ERROR("my_fortran_module",
+ "Error - Open GENIE Version mismatch",
+ "Please re-compile this module")
ENDIF
C All user code goes here, generally the format will be to access some
C data using the helper functions, process it via new or exising user
C written subroutines, and finally return any modified parameters using the
C helper functions
RETURN
END
There are three sorts of helper functions provided by the FORTRAN module interface. They are all listed below
| Commands to obtain data from Open GENIE | Description |
| MODULE_GET_DOUBLE | Reads a double precision real from the PARS workspace |
| MODULE_GET_INT | Reads an integer from the PARS workspace |
| MODULE_GET_REAL | Reads a real from the PARS workspace |
| MODULE_GET_STRING | Reads a string from the PARS workspace |
| MODULE_GET_DOUBLE_ARRAY | Reads a double precision real array from the PARS workspace |
| MODULE_GET_INT_ARRAY | Reads an integer array from the PARS workspace |
| MODULE_GET_REAL_ARRAY | Reads a real array from the PARS workspace |
| MODULE_GET_STRING_ARRAY | Reads a string array from the PARS workspace |
| Commands to return data to Open GENIE | Description |
| MODULE_PUT_DOUBLE | Replaces a double precision real in the PARS workspace |
| MODULE_PUT_INT | Replaces an integer in the PARS workspace |
| MODULE_PUT_REAL | Replaces a real in the PARS workspace |
| MODULE_PUT_STRING | Replaces a string in the PARS workspace |
| MODULE_PUT_DOUBLE_ARRAY | Replaces an double precision real array in the PARS workspace |
| MODULE_PUT_INT_ARRAY | Replaces an integer array in the PARS workspace |
| MODULE_PUT_REAL_ARRAY | Replaces an real array in the PARS workspace |
| MODULE_PUT_STRING_ARRAY | Replaces an string array in the PARS workspace |
| MODULE_PUT_ND_REAL_ARRAY | Replaces an n-dimensional real array in the PARS workspace |
| Commands to communicate with the user | Description |
| MODULE_PRINT | Prints to the terminal |
| MODULE_INFORMATION | Prints to the terminal as an informational message (in blue) |
| MODULE_ERROR | Prints a formatted error message |
All commands to read data from Genie into a user program start with the "module_get_" prefix, and have their first two parameters in common. The first parameter, called PARS_GET, is an EXTERNAL entity passed by Genie. The second parameter, NAME, is a character variable which is the label assigned to the variable in GCL when the parameters workspace was created. For arrays, a LENGTH variable must also be passed; on input this should be set to the maximum allowed number of points, and on output it will be set to the number actually read. If too many points are passed out from GCL, LENGTH will still indicate how many were passed, but the number actually read will be the length of the array which was passed as input; thus testing LENGTH on return provides a check for array overflow.
There is no need for MODULE_GET_ND_REAL_ARRAY to correspond to the MODULE_PUT_ND_REAL_ARRAY function because an array can always be converted to 1-D using the Redim() command from GCL before passing it out.
The subroutine names and parameter types and names are given below:
MODULE_GET_DOUBLE (EXTERNAL PARS_GET, CHARACTER*80 NAME, REAL*8 VALUE) MODULE_GET_INT (EXTERNAL PARS_GET, CHARACTER*80 NAME, INTEGER VALUE) MODULE_GET_REAL (EXTERNAL PARS_GET, CHARACTER*80 NAME, REAL VALUE) MODULE_GET_STRING (EXTERNAL PARS_GET, CHARACTER*80 NAME, CHARACTER*512 VALUE)
MODULE_GET_DOUBLE_ARRAY (EXTERNAL PARS_GET, CHARACTER*80 NAME, REAL*8 VALUE(*), INTEGER LENGTH) MODULE_GET_INT_ARRAY (EXTERNAL PARS_GET, CHARACTER*80 NAME, INTEGER VALUE(*), INTEGER LENGTH) MODULE_GET_REAL_ARRAY (EXTERNAL PARS_GET, CHARACTER*80 NAME, REAL VALUE(*), INTEGER LENGTH) MODULE_GET_STRING_ARRAY (EXTERNAL PARS_GET, CHARACTER*80 NAME, CHARACTER*512(*) VALUE, INTEGER LENGTH)
These commands return data to Open GENIE by replacing the fields in the PARS workspace, otherwise they are very similar to the corresponding "module_get_" commands. The NAME parameter will be the field name in the result workspace returned to GCL, and the LENGTH parameter for the array routines will indicate how many data points to send.
The subroutine names and parameter types and names are given below:
MODULE_PUT_DOUBLE (EXTERNAL PARS_PUT, CHARACTER*80 NAME, REAL*8 VALUE) MODULE_PUT_INT (EXTERNAL PARS_PUT, CHARACTER*80 NAME, INTEGER VALUE) MODULE_PUT_REAL (EXTERNAL PARS_PUT, CHARACTER*80 NAME, REAL VALUE) MODULE_PUT_STRING (EXTERNAL PARS_PUT, CHARACTER*80 NAME, CHARACTER*512 VALUE)
MODULE_PUT_DOUBLE_ARRAY (EXTERNAL PARS_PUT, CHARACTER*80 NAME, REAL*8 VALUE(*), INTEGER LENGTH)
MODULE_PUT_INT_ARRAY (EXTERNAL PARS_PUT, CHARACTER*80 NAME, INTEGER VALUE(*), INTEGER LENGTH)
MODULE_PUT_REAL_ARRAY (EXTERNAL PARS_PUT, CHARACTER*80 NAME, REAL VALUE(*), INTEGER LENGTH)
MODULE_PUT_STRING_ARRAY (EXTERNAL PARS_PUT, CHARACTER*80 NAME, CHARACTER*512(*) VALUE, INTEGER LENGTH)
MODULE_PUT_ND_REAL_ARRAY(EXTERNAL PARS_PUT, CHARACTER*80 NAME, REAL VALUE(*),
INTEGER DIMS_ARRAY(NDIMS), INTEGER NDIMS)
These provide a means for a FORTRAN program to send messages to the user through the standard Open GENIE messaging system. This means, for example that informational messages can be switched off using the Toggle/Info command as with ordinary Open GENIE informational messages. Using these routines ensures that the timing of output messages will be properly synchronized with Open GENIE.
The subroutine names and parameter types and names are given below:
MODULE_PRINT (CHARACTER*(*) MESSAGE) MODULE_INFORMATION (CHARACTER*(*) MESSAGE) MODULE_ERROR (CHARACTER*(*) FUNCTION_NAME, ERROR_MESSAGE, POSSIBLE_SOLUTION)