Learn more about MATLAB

mexCallMATLAB (C and Fortran) - Call MATLAB function or user-defined M-file or MEX-file

C Syntax

#include "mex.h"
int mexCallMATLAB(int nlhs, mxArray *plhs[], int nrhs,
  mxArray *prhs[], const char *functionName);

Fortran Syntax

integer*4 mexCallMATLAB(nlhs, plhs, nrhs, prhs, functionName)
integer*4 nlhs, nrhs
mwPointer plhs(*), prhs(*)
character*(*) functionName

Arguments

nlhs: Number of desired output arguments.
plhs: Array of pointers to output arguments.
nrhs: Number of input arguments.
prhs: Array of pointers to input arguments.
functionName: Character string containing the functionName of the MATLAB built-in, operator, M-file, or MEX-file that you are calling.

Returns

0 if successful, and a nonzero value if unsuccessful.

Description

Call mexCallMATLAB to invoke internal MATLAB numeric functions, MATLAB operators, M-files, or other MEX-files. Both mexCallMATLAB and mexEvalString execute MATLAB commands. However, mexCallMATLAB provides a mechanism for returning results (left-hand side arguments) back to the MEX-file; mexEvalString provides no way for return values to be passed back to the MEX-file.

For a complete description of the input and output arguments passed to functionName, see mexFunction. When calling the mexCallMATLAB function, the number of output arguments nlhs and input arguments nrhs must be less than or equal to 50.

MATLAB allocates dynamic memory to store the mxArrays in plhs. MATLAB automatically deallocates the dynamic memory when you clear the MEX-file. However, if heap space is at a premium, you may want to call mxDestroyArray when you are finished with the mxArrays plhs points to.

If functionName is an operator, place the operator inside a pair of single quotes, for example, '+'.

It is possible to generate an object of type mxUNKNOWN_CLASS using mexCallMATLAB. For example, if you create an M-file that returns two variables but assigns only one of them a value:

function [a,b]=foo(c)
a=2*c;

you get this warning message in MATLAB:

Warning: One or more output arguments not assigned 
during call to 'foo'.

MATLAB assigns output b to an empty matrix. If you then call foo using mexCallMATLAB, the unassigned output variable is given type mxUNKNOWN_CLASS.

Error Handling

If functionName detects an error, MATLAB terminates the MEX-file and returns control to the MATLAB prompt. If you want to trap errors, use the mexCallMATLABWithTrap function.

C Examples

See mexcallmatlab.c in the matlabroot/extern/examples/mex folder .

Additional examples:

sincall.c in the matlabroot/extern/examples/refbook folder
mexevalstring.c and mexsettrapflag.c in the matlabroot/extern/examples/mex folder
mxcreatecellmatrix.c and mxisclass.c in the matlabroot/extern/examples/mx folder