Main Content

mexCallMATLAB (C)

Call MATLAB function, user-defined function, or MEX function

C Syntax

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

Description

Note

To write MEX functions using modern C++ features and the MATLAB Data API for C++, see Write C++ Functions Callable from MATLAB (MEX Files).

Call mexCallMATLAB to invoke internal MATLAB® numeric functions, MATLAB operators, user-defined functions, or other MEX functions.

Both mexCallMATLAB and mexEvalString execute MATLAB commands. Use mexCallMATLAB for returning results (left side arguments) back to the MEX function. The mexEvalString function does not return values to the MEX function.

Input Arguments

expand all

Number of expected output mxArrays, specified as an integer less than or equal to 50.

Array of pointers to the mxArray output arguments.

Caution

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

Number of input mxArrays, specified as an integer less than or equal to 50.

Array of pointers to the mxArray input arguments.

Name of the MATLAB built-in function, operator, user-defined function, or MEX function to call specified as const char*.

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

Output Arguments

expand all

The function returns 0 if successful, and a nonzero value if unsuccessful.

Error Handling

If functionName detects an error, MATLAB terminates the MEX function 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 these examples in matlabroot/extern/examples/mex:

See these examples in matlabroot/extern/examples/refbook:

See these examples in matlabroot/extern/examples/mx:

Tips

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

Version History

Introduced before R2006a