\section{How to use CTL/C++ components from MATLAB}
\label{mexglx}

Contrary to the Java case, calling CTL/C++ components is much more difficult.
One needs to compile a shared library, called a MEX-file that is executable from
within Matlab. To achieve that, Matlab ships with a compiler, which is also
called mex, which can build such a shared library. This section will describe
how to write such a function manually first and then will present a code-generator
which parses Component Interfaces (CIs) and generates C++ code which can be
compiled into a \textit{mexglx} file, which is the name for the executable
format described above.

\subsection{Manual approach}

\lstinputlisting[caption={Example mexFunction}]{sample/mexglx/add.cpp}

The name of the \textit{mexglx} file is used as the function name by Matlab and
the mexFunction() is the function that will be called. It needs to have the
signature seen above, with the following arguments:

\begin{enumerate}
\item The number of results expected by the caller
\item The array to which those results are passed
\item The number of arguments
\item The array of those arguments
\end{enumerate}

MATLAB's \textit{mex.h} header defines the type \textit{mxArray} which used to
pass data to Matlab or to receive data from it. It also defines helper functions
for converting those to C++ types, for example \textit{mxGetScalar()} which
retrieves an integer from an \textit{mxArray}. This means that the mexFunction
has three tasks to fulfill: convert the arguments to C++ types, make a call
to one or more functions provided by CTL components and finally convert the
results back into Matlab types. You can compile a mexglx like this:

\begin{verbatim}
$ /path/to/mex add.cpp
\end{verbatim}

This will create a file called \textit{add.mexglx} and if it is found by Matlab
(by either being in its path or in the current working directory), it can be called
as \textit{add()}.

\subsection{Automatic approach}

As shown in the last section, all of the work needed to call C++ functions
from Matlab can be automated. This section introduces such an automatism:
\textit{ctlmex.py}, which takes a CI as input and outputs all the code
which is necessary to enable Matlab to call the function specified there.
To simplify the generated code, there is are helper functions for converting
from C types to Matlab types and vice versa (see \textit{mexhelper.cpp} if you are
interested in the dirty details). There is one prebuild mex-function, 
\textit{use()}, which specifies the location of specific CTL components, just
like its counterpart in C++. While all of this sounds like a rather complicated
process, you should be able to convert functional CIs by just running
\textit{ctlmex.py} and then using the resulting \textit{mexglx} files like this:

\begin{verbatim}
use('AddRi', 'add/add.exe -l pipe')
res = add2(3, 4)
\end{verbatim}

\subsubsection{Limitations}

\begin{itemize}
	\item There is currently no support for classes or libraries.
	\item The custom vector class of mexhelper treats all vector as column
	vectors.
	\item Conversion from mxArray to std::string and vice versa is not yet
	implemented.
	\item Due to their nature as normal shared objects, any segmentation
	faults or similar problems in the \textit{mexglx} files will cause 
	MATLAB to crash.
\end{itemize}

\subsubsection{Example 2: Gaussian elimination}

In this section, a more sophisticated example will be developed using 
\textit{ctlmex.py}, which demonstrates that vectors and matrices can also be
automatically converted. 

Firstly, a C++ implementation of the Gaussian elimination algorithm is needed,
which will then be componentized and coupled with MATLAB using \textit{mex}.

\lstinputlisting[caption={Gaussian elimination}]{sample/mexglx/gauss.h}

The algorithm uses the matrix- and vector-classes from \textit{mexhelper.h},
which provide the necessary addition and multiplication operators.

\lstinputlisting[caption={Component interface}]{sample/mexglx/lineq.ci}
\lstinputlisting[caption={Connecting the implementation}]{sample/mexglx/lineq.cpp}

The CI just defines the \textit{solve()} template function for solving a system of
linear equations of the form $A * x = b$. The \textit{CTL\_connect()} is also
quite straightforward: the function is specialized for \textit{double} and 
connected. The \textit{ifdefs} are needed, because newer CTL version (which
incidentally define \textbf{CTL\_VER}) have merged the former separate 
\textit{connect()} and \textit{connectID()} functions.

You can now run \textit{ctlmex.py} and generate the mexglx wrapper code:

\begin{verbatim}
$ ctlmex.py lineq.ci >lineq_mlab.cpp
\end{verbatim}

\lstinputlisting[caption={mexglx wrapper code for the LinEq CI}]{sample/static/lineq_mlab.cpp}

The code is of course very similar to the one presented earlier, but uses the
\textit{mexConvert()} template function to do the conversion automatically.

\subsection{How to run}

Running mexglx-files is identical to using standard .m files, as seen above,
however you need to specify a location for the CTL component using the 
\textit{use()} function (implementation details in use.cpp).

\lstinputlisting[caption={Running the Gauss example}]{sample/mexglx/test2.m}

%- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

\section{How to use CTL4j components from MATLAB}

This works pretty straightforward, because Matlab comes with support for calling Java
code in scripts. However, generics are not supported and therefore you cannot use
Location.parseFile() as it returns a LinkedList$<$String$>$. In addition to that,
it might be necessary to modify MATLAB's CLASSPATH so that it can find the CTL4j
classes. Apart from that, the code almost looks like a standard CTL4j client application:

\begin{verbatim}
javaaddpath('/path/to/jsch-20041105-1.4.jar')
javaaddpath('/path/to/ctl4j/build')

loc = CTL.Types.Location('user@host:/path/to/ctl4j/src/Example.Server tcp')
proc = CTL.Process(loc)
javaSys.CTestCI.use(proc)
test = javaSys.CTestCI()
test.add(3, 4)
proc.stopService()
\end{verbatim}

In contrast to a standard Java client, created processes are not stopped
automatically, you need to do that manually at the end of your Matlab script.