mexFunction Gateway Routine

The gateway routine is the entry point to the MEX file. It is through this routine that MATLAB^® accesses the rest of the routines in your MEX files. The name of the gateway routine is mexFunction. It takes the place of the main program in your source code.

Naming the MEX File

The name of the source file containing mexFunction is the name of your MEX file, and, hence, the name of the function you call in MATLAB. Name your Fortran source file with an uppercase .F file extension.

The file extension of the binary MEX file is platform-dependent. You find the file extension using the mexext function, which returns the value for the current machine.

Difference Between .f and .F Files

To ensure that your Fortran MEX file is platform independent, use an uppercase .F file extension.

Fortran compilers assume source files using a lowercase .f file extension have been preprocessed. On most platforms, mex makes sure that the file is preprocessed regardless of the file extension. However, on Apple Macintosh platforms, mex cannot force preprocessing.

Required Parameters

The Fortran signature for mexfunction is:

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

Place this subroutine after your computational routine and any other subroutines in your source file.

The following table describes the parameters for mexFunction.

Declare prhs and plhs as type mwPointer, which means they point to MATLAB arrays. They are vectors that contain pointers to the arguments of the MEX file.

You can think of the name prhs as representing the “parameters, right-hand side,” that is, the input parameters. Likewise, plhs represents the “parameters, left side,” or output parameters.

Managing Input and Output Parameters

Input parameters (found in the prhs array) are read-only; do not modify them in your MEX file. Changing data in an input parameter can produce undesired side effects.

You also must take care when using an input parameter to create output data or any data used locally in your MEX file. If you want to copy an input array into an output array, for example plhs(1), call the mxDuplicateArray function to make of copy of the input array. For example:

plhs(1) = mxDuplicateArray(prhs(1)) 

For more information, see the troubleshooting topic Incorrectly Constructing a Cell or Structure mxArray.

Validating Inputs

For a list of functions to validate inputs to your subroutines, see the Matrix Library category, Validate Fortran Data. The mxIsClass function is a general-purpose way to test an mxArray.

Computational Routine

The computational routine contains the code for performing the computations you want implemented in the binary MEX file. Although not required, consider writing the gateway routine, mexFunction, to call a computational routine. To validate input parameters and to convert them into the types required by the computational routine, use the mexFunction code as a wrapper.

If you write separate gateway and computational routines, you can combine them into one source file or into separate files. If you use separate files, the file containing mexFunction must be the first source file listed in the mex command.