MATLAB Fortran API Libraries

The Fortran Matrix API and the Fortran MEX API describe functions you can use in your gateway and computational routines that interact with MATLAB® programs and the data in the MATLAB workspace.

To use these functions, include the fintrf header, which declares the entry point and interface routines. The file is in your matlabroot\extern\include folder. Put this statement in your source file:

#include "fintrf.h"

Matrix Library

Use Fortran Matrix API functions to pass mxArray, the type MATLAB uses to store arrays, to and from MEX files. For examples using these functions, see matlabroot/extern/examples/mx.

MEX Library

Use Fortran MEX API functions to perform operations in the MATLAB environment. For examples using these functions, see matlabroot/extern/examples/mex.

Unlike MATLAB functions, MEX file functions do not have their own variable workspace. MEX file functions operate in the caller workspace. To evaluate a string, use mexEvalString. To get and put variables into the caller workspace, use the mexGetVariable and mexPutVariable functions.

Preprocessor Macros

The Matrix and MEX libraries use the MATLAB preprocessor macros mwSize and mwIndex for cross-platform flexibility. mwSize represents size values, such as array dimensions and number of elements. mwIndex represents index values, such as indices into arrays.

MATLAB has an extra preprocessor macro for Fortran files, mwPointer. MATLAB uses a unique data type, the mxArray. Because you cannot create a data type in Fortran, MATLAB passes a special identifier, created by the mwPointer preprocessor macro, to a Fortran program. This is how you get information about an mxArray in a native Fortran data type. For example, you can find out the size of the mxArray, determine whether it is a string, and look at the contents of the array. Use mwPointer to build platform-independent code.

The Fortran preprocessor converts mwPointer to integer*4 when building binary MEX files on 32-bit platforms and to integer*8 when building on 64-bit platforms.


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

Using the Fortran %val Construct

The Fortran %val(arg) construct specifies that an argument, arg, is to be passed by value, instead of by reference. Most, but not all, Fortran compilers support the %val construct.

If your compiler does not support the %val construct, copy the array values into a temporary true Fortran array using the mxCopy* routines (for example, mxCopyPtrToReal8).

%val Construct Example

If your compiler supports the %val construct, you can use routines that point directly to the data (that is, the pointer returned by typed data access functions like mxGetDoubles or mxGetComplexDoubles). You can use %val to pass the contents of this pointer to a subroutine, where it is declared as a Fortran double-precision matrix.

For example, consider a gateway routine that calls its computational routine, yprime, by:

call yprime(%val(yp), %val(t), %val(y))

If your Fortran compiler does not support the %val construct, you would replace the call to the computational subroutine with:

C Copy array pointers to local arrays.
       call mxCopyPtrToReal8(t, tr, 1)
       call mxCopyPtrToReal8(y, yr, 4)
C Call the computational subroutine.
       call yprime(ypr, tr, yr)
C Copy local array to output array pointer.
       call mxCopyReal8ToPtr(ypr, yp, 4)

You must also add the following declaration line to the top of the gateway routine:

real*8 ypr(4), tr, yr(4)

If you use mxCopyPtrToReal8 or any of the other mxCopy* routines, the size of the arrays declared in the Fortran gateway routine must be greater than or equal to the size of the inputs to the MEX file coming in from MATLAB. Otherwise, mxCopyPtrToReal8 does not work correctly.

See Also

| | | | |