External Interfaces |
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:
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.
In this figure a call to the MEX-file named func
of the form [C, D] = func(A,B)
tells MATLAB to pass variables A
and B
to your MEX-file. C
and D
are left unassigned.
The func.f
gateway routine uses the mxCreate
function to create the MATLAB arrays for your output arguments. It sets plhs[0], [1], ...
to the pointers to the newly created MATLAB arrays. It uses the mxGet
functions to extract your data from prhs[0], [1], ...
Finally, it calls your Fortran subroutine, passing the input and output data pointers as function parameters using %val
.
On return to MATLAB, plhs[0]
is assigned to C
and plhs[1]
is assigned to D
.
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:
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.
To use pointers properly, you must declare them to be the correct size. Declare pointers 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.
The Gateway Routine
The entry point to the gateway subroutine must be named mexFunction
and must contain these parameters.
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
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
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 |
© 1994-2005 The MathWorks, Inc.