mexCallMATLAB (Fortran)

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

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

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.

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 function to call.

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 function. The mexEvalString function does not return values to the MEX function.

For a complete description of the input and output arguments passed to functionName, see 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 these examples in matlabroot/extern/examples/refbook:

sincall.F

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

mxcreatecellmatrixf.F

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.

Documentation