No BSD License  

Highlights from
engCallMATLAB

image thumbnail

engCallMATLAB

by

 

13 Nov 2007 (Updated )

engCallMATLAB is a c routine giving engine equivalent of mexCallMATLAB function

engCallMATLAB.m
%*************************************************************************************
% *
% * 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.
% *
% ******************************************************************************/

Contact us