Creating Fortran MEX-Files (External Interfaces/API)

External Interfaces/API

Fortran MEX-Files

Fortran MEX-files are built by using the mex script to compile your Fortran source code with additional calls to API routines.

MEX-files in Fortran, like their C counterparts, can create any data type supported by MATLAB. You can treat Fortran MEX-files, once compiled, exactly like M-functions.

The Components of a Fortran MEX-File

This section discusses the specific elements needed in a Fortran MEX-file. The source code for a Fortran MEX-file, like the C MEX-file, consists of two distinct parts:

A computational routine that contains the code for performing the computations that you want implemented in the MEX-file. Computations can be numerical computations as well as inputting and outputting data.
A gateway routine that interfaces the computational routine with MATLAB by the entry point mexFunction and its parameters prhs, nrhs, plhs, nlhs, where prhs is an array of right-hand input arguments, nrhs is the number of right-hand input arguments, plhs is an array of left-hand output arguments, and nlhs is the number of left-hand output arguments. The gateway calls the computational routine as a subroutine.

The computational and gateway routines may be separate or combined. The following figure, Fortran MEX Cycle, shows how inputs enter an API function, what functions the gateway routine performs, and how output returns to MATLAB.

Figure 3-1: Fortran MEX Cycle

The Pointer Concept

The MATLAB API works with a unique data type, the mxArray. Because there is no way to create a new data type in Fortran, MATLAB passes a special identifier, called a pointer, to a Fortran program. You can get information about an mxArray by passing this pointer to various API functions called Access Routines. These access routines allow you to get a native Fortran data type containing exactly the information you want, i.e., the size of the mxArray, whether or not it is a string, or its data contents.

There are several implications when using pointers in Fortran:

The %val construct.

If your Fortran compiler supports the %val construct, then there is one type of pointer you can use without requiring an access routine, namely a pointer to data (i.e., the pointer returned by mxGetPr or mxGetPi). You can use %val to pass this pointer's contents to a subroutine, where it is declared as a Fortran double-precision matrix.

If your Fortran compiler does not support the %val construct, you must use the mxCopy__ routines (e.g., mxCopyPtrToReal8) to access the contents of the pointer. For more information about the %val construct and an example, see the section, The %val Construct.

Variable declarations.

To use pointers properly, you must declare them to be the correct size. On DEC Alpha machines, all pointers should be declared as integer*8. On all other platforms, pointers should be declared as integer*4.

If your Fortran compiler supports preprocessing with the C preprocessor, you can use the preprocessing stage to map pointers to the appropriate declaration. In UNIX, see the examples ending with .F in the examples directory for a possible approach.

Caution Declaring a pointer to be the incorrect size may cause your program to crash.

The Gateway Routine

The entry point to the gateway subroutine must be named mexFunction and must contain these parameters.

subroutine mexFunction(nlhs, plhs, nrhs, prhs)
integer plhs(*), prhs(*)
integer nlhs, nrhs

Note Fortran is case-insensitive. This document uses mixed-case function names for ease of reading.

In a Fortran MEX-file, the parameters nlhs and nrhs contain the number of left- and right-hand arguments with which the MEX-file is invoked. prhs is a length nrhs array that contains pointers to the right-hand side inputs to the MEX-file, and plhs is a length nlhs array that contains pointers to the left-hand side outputs that your Fortran function generates.

In the syntax of the MATLAB language, functions have the general form

```
[a,b,c,...] = fun(d,e,f,...)
```

where the ellipsis (...) denotes additional terms of the same format. The a,b,c,... are left-hand arguments and the d,e,f,... are right-hand arguments.

As an example of the gateway routine, consider invoking a MEX-file from the MATLAB workspace with the command

```
x = fun(y,z);
```

the MATLAB interpreter calls mexFunction with the arguments

plhs is a 1-element C array where the single element is a null pointer. prhs is a 2-element C array where the first element is a pointer to an mxArray named Y and the second element is a pointer to an mxArray named Z.

The parameter plhs points at nothing because the output x is not created until the subroutine executes. It is the responsibility of the gateway routine to create an output array and to set a pointer to that array in plhs(1). If plhs(1) is left unassigned, MATLAB prints a warning message stating that no output has been assigned.

Note It is possible to return an output value even if nlhs = 0. This corresponds to returning the result in the ans variable.

The gateway routine should validate the input arguments and call mexErrMsgTxt if anything is amiss. This step includes checking the number, type, and size of the input arrays as well as examining the number of output arrays. The examples included later in this section illustrate this technique.

The mx functions provide a set of access methods (subroutines) for manipulating MATLAB arrays. These functions are fully documented in the online API reference pages. The mx prefix is shorthand for mxArray and it means that the function enables you to access and/or manipulate some of the information in the MATLAB array. For example, mxGetPr gets the real data from the MATLAB array. Additional routines are provided for transferring data between MATLAB arrays and Fortran arrays.

The gateway routine must call mxCreateDoubleMatrix, mxCreateSparse, or mxCreateString to create MATLAB arrays of the required sizes in which to return the results. The return values from these calls should be assigned to the appropriate elements of plhs.

The gateway routine may call mxCalloc to allocate temporary work arrays for the computational routine if it needs them.

The gateway routine should call the computational routine to perform the desired calculations or operations. There are a number of additional routines that MEX-files can use. These routines are distinguished by the initial characters mex, as in mexCallMATLAB and mexErrMsgTxt.

When a MEX-file completes its task, it returns control to MATLAB. Any MATLAB arrays that are created by the MEX-file that are not returned to MATLAB through the left-hand side arguments are automatically destroyed.

Creating Fortran MEX-Files The %val Construct