## Introduction

In two past articles (Solving Engineering Problems Using MATLAB C API and Solving Engineering Problems Using MATLAB C++ Math Library), I show you how can a programmer develop an application that using MATLAB features like computing complex engineering problems. But if you are not familiar with MATLAB APIs or MATLAB C++ interface or these are hard coding techniques, this article is for you.

## MATLAB Engine

MATLAB provides some API functions for controlling it. These APIs required that you installed MATLAB on your target machine. We named these APIs, MATLAB Engine API. For an alternative method, you can use MATLAB ActiveX control. For more information refer to article: A class wrapper for Matlab (C) ActiveX Control by Jonathan de Halleux.

## Using MATLAB Engine

For using MATLAB engine, you must follow these steps:

- Add matlab.h interface file to stdafx.h or any desired interface/implementation file.
- Add MATLAB libraries to your project. For this reason, we need these libraries: libeng.lib, libmx.lib, libmatlb.lib, libmat.lib, libmmfile.lib.
- Add MatlabEng.h and MatlabEng.cpp files to your project.
- Declare a variable with type of
`CMatlabEng`

. (Remember to include MatlabEng.h interface file).
- Use member functions of
`CMatlabEng`

class, to control MATLAB and send commands to it and retrieve computed values or plotted graphs!
- Compile your project.

## CMatlabEng

Following codes are definition of `CMatlabEng`

class. It's very simple to use.

class CMatlabEng {
public:
int OutputBuffer(char *p, int n);
void OpenSingleUse(const char *startcmd, void *dcom, int *retstatus);
int GetVisible(bool* value);
int SetVisible(bool value); mxArray* GetVariable(const char* name);
int PutVariable(const char *name, const mxArray *mp);
int EvalString(const char* string);
void Open(const char* StartCmd); int Close(); CMatlabEng();
virtual ~CMatlabEng();
protected:
Engine* pEng;
};

## CMatlabEng in detail

Table 1 is a complete reference of member functions of `CMatlabEng`

class.

**Member Function** | **Description** |

`int OutputBuffer(char *p, int n);` | `OutputBuffer` defines a character buffer for `EvalString` to return any output that ordinarily appears on the screen. The default behavior of EvalString is to discard any standard output caused by the command it is executing. `OutputBuffer (p,n)` tells any subsequent calls to EvalString to save the first n characters of output in the character buffer pointed to by p. To turn off output buffering, use `OutputBuffer(ep,NULL,0);` |

`void OpenSingleUse (const char *startcmd, void *dcom, int *retstatus);` | This routine allows you to start multiple MATLAB processes for the purpose of using MATLAB as a computational engine. OpenSingleUse starts a MATLAB process, establishes a connection, and returns a unique engine identifier, or `NULL` if the open fails. OpenSingleUse starts a new MATLAB process each time it is called. OpenSingleUse opens a COM channel to MATLAB. This starts the MATLAB that was registered during installation. If you did not register during installation, on the command line you can enter the command:
**matlab /regserver**
`OpenSingleUse` allows single-use instances of a MATLAB engine server. `OpenSingleUse` differs from Open, which allows multiple users to use the same MATLAB engine server. |

`int GetVisible (bool* value);` | Returns status of the window for the MATLAB engine session, is visible or invisible on the Windows desktop. |

`int SetVisible (bool value);` | `SetVisible` makes the window for the MATLAB engine session, either visible or invisible on the Windows desktop. You can use this function to enable or disable user interaction with the MATLAB engine session. |

`mxArray* GetVariable (const char* name);` | Reads the named `mxArray` from the MATLAB engine session associated with ep and returns a pointer to a newly allocated `mxArray` structure, or `NULL` if the attempt fails. `GetVariable` fails if the named variable does not exist. Be careful in your code to free the mxArray created by this routine when you are finished with it. |

`int PutVariable (const char *name, const mxArray *mp);` | `PutVariable` writes `mxArray` mp to the engine ep, giving it the variable name, name. If the `mxArray` does not exist in the workspace, it is created. If an `mxArray` with the same name already exists in the workspace, the existing `mxArray` is replaced with the new `mxArray` . |

`int EvalString (const char* string);` | Evaluates the expression contained in string for the MATLAB engine session, previously started by `Open` . |

`void Open (const char* StartCmd);` | This routine allows you to start a MATLAB process for the purpose of using MATLAB as a computational engine. |

`int Close();` | This routine allows you to quit a MATLAB engine session. |

## Sample Program

Following program is a sample that uses `CMatlabEng`

class. Program logic is very simple.

#include <span class="code-string">"stdafx.h"</span>
#include <span class="code-string">"MatlabEng.h"</span>
#define message(x) printf(x"\n\n")
int main(int argc, char* argv[])
{
CMatlabEng matlab;
//open new matlab session
message("Starting MATLAB");
matlab.Open(NULL);
message("Hiding MATLAB");
matlab.SetVisible(FALSE);
message("Press any key to continue");
getch();
message("Showing MATLAB");
matlab.SetVisible(TRUE);
message("Press any key to continue");
getch();
mxArray *T = NULL;
double time[10] = { 0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0 };
//create matrix
T = mxCreateDoubleMatrix(1, 10, mxREAL);
memcpy((void *)mxGetPr(T), (void *)time, sizeof(time));
//send matrix T to matlab
message("Send matrix T to matlab");
matlab.PutVariable("T", T);
//Evaluate matlab command
matlab.EvalString("D = .5.*(-9.8).*T.^2;");
//Plot results
message("Plot(T, D)");
matlab.EvalString("plot(T,D);");
matlab.EvalString("title('Position vs. Time for a falling object');");
matlab.EvalString("xlabel('Time (seconds)');");
matlab.EvalString("ylabel('Position (meters)');");
matlab.EvalString("grid;");
//pause to see results
message("Press any key to continue");
getch();
//destroy matrix
mxDestroyArray(T);
//show MATLAB graphics capabilities
message("Showing MATLAB graphics capabilities");
matlab.EvalString("z=peaks(25);");
matlab.EvalString("surf(z);");
matlab.EvalString("colormap(jet);");
matlab.EvalString("knot;");
//pause
getch();
//close session
matlab.Close();
return 0;
}

Enjoy!