C Syntax

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

Fortran Syntax

#include "fintrf.h"
integer*4 mexCallMATLAB(nlhs, plhs, nrhs, prhs, functionName)
integer*4 nlhs, nrhs
mwPointer plhs(*), prhs(*)
character*(*) functionName

Arguments

nlhs

Number of output arguments. Must be less than or equal to 50.

plhs

Array of pointers to output arguments

nrhs

Number of input arguments. Must be less than or equal to 50.

prhs

Array of pointers to input arguments

functionName

Character string containing name of the MATLAB^® built-in function, operator, user-defined function, or MEX file you are calling

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

Returns

0 if successful, and a nonzero value if unsuccessful.

Description

Call mexCallMATLAB to invoke internal MATLAB numeric functions, MATLAB operators, user-defined functions, or other MEX files. Both mexCallMATLAB and mexEvalString execute MATLAB commands. Use mexCallMATLAB for returning results (left side arguments) back to the MEX file. The mexEvalString function cannot return values to the MEX file.

For a complete description of the input and output arguments passed to functionName, see mexFunction.

Tips

• MATLAB allocates dynamic memory to store the arrays in plhs for mexCallMATLAB. MATLAB automatically deallocates the dynamic memory when you exit the MEX file. However, if heap space is at a premium, call mxDestroyArray when you are finished with the arrays in plhs.

  Note:   The plhs argument for mexCallMATLAB is not the same as the plhs for mexFunction. Do not destroy an mxArray returned in plhs for mexFunction.

Error Handling

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

Limitations

• Avoid using the mexCallMATLAB function in Simulink^® S-functions. If you do, do not store the resulting plhs mxArray pointers in any S-function block state that persists after the MEX function finishes. Outputs of mexCallMATLAB have temporary scope and are automatically destroyed at the end of the MEX function call.

• It is possible to generate an object of type mxUNKNOWN_CLASS using mexCallMATLAB. For example, this function returns two variables but only assigns one of them a value.

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

  If you then call foo using mexCallMATLAB, the unassigned output variable is now type mxUNKNOWN_CLASS.

Examples

See the following examples in matlabroot/extern/examples/mex.

• mexcallmatlab.c

• mexevalstring.c

• mexcallmatlabwithtrap.c

See the following examples in matlabroot/extern/examples/refbook.

• sincall.c

• sincall.F

See the following examples in matlabroot/extern/examples/mx.

• mxcreatecellmatrix.c

• mxcreatecellmatrixf.F

• mxisclass.c

See Also

mexFunction, mexCallMATLABWithTrap, mexEvalString, mxDestroyArray