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`

function in your source code.

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.

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.

The signature for `mexfunction`

is:

void mexFunction( int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[])

Place this function after your computational routine and any other functions in your source file.

The following table describes the parameters for `mexFunction`

.

Parameter | Description |
---|---|

`prhs` | Array of right-side input arguments. |

`plhs` | Array of left-side output arguments. |

`nrhs` | Number of right-side arguments, or the size of the `prhs` array. |

`nlhs` | Number of left-side arguments, or the size of the `plhs` array. |

Declare `prhs`

and `plhs`

as
type `mxArray *`

, which means they point to MATLAB arrays.
They are vectors that contain pointers to the arguments of the MEX file. The keyword `const`

,
which modifies `prhs`

, means that your MEX file does not modify
the input arguments.

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-hand side," or 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. To copy an input array into
a locally defined variable, `myData`

, call the `mxDuplicateArray`

function
to make of copy of the input array. For example:

mxArray *myData = mxCreateStructMatrix(1,1,nfields,fnames); mxSetField(myData,0,"myFieldName",mxDuplicateArray(prhs[0]));

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

.

For a list of functions to validate inputs to your functions, see the Matrix Library category, Validate Data.

The `mxIsClass`

function is a general-purpose
way to test an `mxArray`

. For example, suppose your
second input argument (identified by `prhs[1]`

) must
be a full matrix of real numbers. To check this condition, use the
following statements.

if(mxIsSparse(prhs[1]) || mxIsComplex(prhs[1]) || mxIsClass(prhs[1],"char")) { mexErrMsgTxt("input2 must be full matrix of real values."); }

This example is not an exhaustive check. You can also test for structures, cell arrays, function handles, and MATLAB objects.

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. Use the `mexFunction`

code
as a wrapper to validate input parameters and to convert them into
the types required by the computational routine.

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.

`mexext`

| `mexFunction`

| `mxDuplicateArray`

| `mxIsClass`

Was this topic helpful?