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?