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:

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 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.

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