%*************************************************************************************
% *
% * MATLAB (R) is a trademark of The Mathworks (R) Corporation
% *
% * eng file: engCallMATLAB.c
% * Programmer: James Tursa
% * Version: 1.0
% * Date: November 12, 2007
% * Copyright: (c) 2007 by James Tursa
% * Permission: Permission is granted to freely distribute and use this code as long
% * as the header information is included.
% *
% * Requires: #include <stdio.h>
% * #include <string.h>
% * #include "engine.h"
% *
% * engCallMATLAB calls a MATLAB function using the MATLAB engine. This is the eng
% * equivalent of the function mexCallMATLAB for mex files. The engine pointer ep
% * must point to an engine that is already opened with the engOpen function.
% *
% * Inputs: ep = Engine pointer (Engine *)
% * nlhs = Number of desired output arguments (int)
% * nrhs = Number of input arguments (int)
% * prhs = Array of pointers to input mxArrays (mxArray *[])
% * name = Name of the function to call (char *)
% *
% * Outputs: plhs = Array of pointers to output mxArrays (mxArray *[])
% * returns 0 = success, 1 = failure
% *
% * Notes: This routine dynamically allocates memory for the return mxArray variables
% * pointed to by the plhs array. It is up to the calling routine to destroy
% * these arrays with the mxDestroyArray routine when done with them.
% *
% * If engCallMATLAB returns a 1 for failure, then none of the plhs pointers
% * will be set to anything, and there will be no need to destroy them.
% *
% * The engCallMATLAB function works as follows:
% * - Builds a command string with the appropriate number of dummy input
% * names (ECMI00, ECMI01, ECMI02, ...) and dummy output names (ECMO00,
% * ECMO01, ECMO02, ...).
% * - Puts the inputs into the MATLAB workspace under the dummy input names.
% * - Calls engEvalString to evaluate the command string.
% * - Gets the resulting dummy outputs from the MATLAB workspace.
% * - Clears all of the temporary variables (ECMI00, ...) from the MATLAB
% * workspace.
% * - If there is an error in any of the above processes, then all of the
% * temporary mxArray variables are destroyed.
% *
% * Because the temporary variables are put into the MATLAB workspace, this
% * routine will only work if you do not have any existing MATLAB workspace
% * variable names that clash with the dummy names that this routine uses.
% * These names are:
% * ECMInn, where nn = any two digit number from 00 - 99
% * ECMOnn, where nn = any two digit number from 00 - 99
% *
% * Example: To evaluate the equivalent of the following MATLAB function
% *
% * [a,b,c] = cart2pol[3,5,7)
% *
% * You would have to have these inputs:
% *
% * ep = pointer to Engine already opened with engOpen
% * nlhs = 3
% * plhs = array at least 3 in size
% * nrhs = 3
% * prhs[0] = pointer to mxArray containing the value 3
% * prhs[1] = pointer to mxArray containing the value 5
% * prhs[2] = pointer to mxArray containing the value 7
% * name = "cart2pol"
% *
% * This routine will build the following command string:
% *
% * [ECMO00,ECMO01,ECMO02]=cart2pol(ECMI00,ECMI01,ECMI02);
% *
% * After putting ECMI00, ECMI01, and ECMI02 into the MATLAB
% * workspace, the engEvalString routine will be called with
% * the command string. Then the result variables ECMO00,
% * ECMO01, and ECMO02 will be gotten from the MATLAB workspace
% * and assigned to the plhs[] array pointers. This routine will
% * then clear all of the MATLAB workspace variables for this
% * example:
% *
% * ECMO00, ECMO01, ECMO02, ECMI00, ECMI01, ECMI02
% *
% ***********************************************************************************/
%
% There is a test driver program available for engCallMATLAB. The help for this
% test driver program is as follows:
%
%*************************************************************************************
% *
% * MATLAB (R) is a trademark of The Mathworks (R) Corporation
% *
% * eng file: testengcallmatlab.c
% * Programmer: James Tursa
% * Version: 1.0
% * Date: November 12, 2007
% * Copyright: (c) 2007 by James Tursa
% * Permission: Permission is granted to freely distribute and use this code as long
% * as the header information is included.
% *
% * testengcallmatlab.c is a test diriver program for the engCallMATLAB function that
% * is provided in the engCallMATLAB.c file. This driver program calculates the
% * results of the function call [a,b,c] = cart2pol(3,5,7). The results are converted
% * to double variables and printed to the console, and they are also put into the
% * MATLAB engine workspace as the variables a, b, and c. The engine is intentionally
% * left running after this progrm ends so that you can examine the results directly
% * in the MATLAB engine. Then the engCallMATLAB function is called again with the
% * function kart2pol, an intentional misspelling of the original name. This will
% * result in a return code a 1 indicating a failure.
% *
% * To compile testengcallmatlab.c with the built in lcc compiler, you can use this
% * m-file for win32 (filename is compile_lcc.m):
% *
% * % Compiles a C main source file. Assumes engine routines are used.
% * % lcc compiler
% * function compile_lcc(name)
% * options = [matlabroot '\bin\win32\mexopts\lccengmatopts.bat'];
% * disp(['Options = ' options]);
% * mex('-f', options, name, '-v');
% * end
% *
% * and invoke it with:
% *
% * >> compile_lcc('testengcallmatlab.c')
% *
% * This should produce an exe file named testengcallmatlab.exe
% *
% * You can execute this at the MATLAB prompt (assuming that you have installed
% * MATLAB as a console) as follows:
% *
% * >> !testengcallmatlab
% *
% * You should see the following output on the console:
% *
% * calls the function cart2pol(3,5,7)
% * engCallMATLAB return code = 0
% * engCallMATLAB return code = 0
% * a = 1.030377
% * b = 5.830952
% * c = 7.000000
% * Intentionally calling with misspelled name kart2pol
% * engCallMATLAB return code = 1
% *
% * And you can examine the variables directly in the MATLAB engine workspace.
% *
% ******************************************************************************/