//=============================================================================
//        THE TANGO BINDING FOR MATLAB - RELEASE 1.5.0
//=============================================================================
  1 - From the author
  2 - Installing
  3 - Using the TANGO binding
  4 - Compiling the project
  5 - Generating standalone TANGO application with the Matlab Compiler

//=============================================================================
// 1 - NOTE FROM THE AUTHOR
//=============================================================================
This is a TANGO binding for Matlab-R12/R13/R14. It gives user access to any 
device within a TANGO control system. This binding is composed of a MEX-file 
and several m-files (approx. 75).

Please send bug report, suggestion or comment to the TANGO mailing list

Have fun with TANGO under Matlab.

Nicolas Leclercq - Synchrotron SOLEIL.

//=============================================================================
// 2 - Installing
//=============================================================================
The <mex-file> directory contains a pre-build MEX-file for Windows-2K/XP
(tango_binding.dll). For Linux (and other Unixes), the MEX-file must be
compiled (see section 4).

There is no special installation process. Just make sure that Matlab can access
the directories <mex-file> and <m-files> that come with this distribution.

//=============================================================================
// 3 - Using the TANGO binding
//=============================================================================

3.1 - Documentation

Each TANGO m-function is self-documented (online documentation). Use the Matlab
<help> function to get information on a particular TANGO m-function (e.g. help
tango_read_attribute). Thanks to Laurent Nadolski (from SOLEIL) for his
contribution on the m-files documentation.

3.2 - Error Handling

Applications generated by the matab compiler (see 5 - Generating standalone TANGO
application with the Matlab Compiler) don't support the matlab try/catch mechanism.
Consequently, the TANGO binding for Matlab implements the so-called "TANGO error
code" to report error to users.

The "TANGO error code" is updated each time a TANGO m-function is
executed from Matlab. It is set to -1 in case of error, 0 otherwise. Always 
check its value before using the any returned data. Here is a typical example:

%- get "unknown command" info
cmd_info = tango_command_query('tango/tangotest/3', 'dummy');
%- always check error
if (tango_error == -1)
  %- handle error here (cmd_info is not valid - DO NOT USE IT)
  %- print error stack
  tango_print_error_stack;
  %- can't continue
  return;
end
%- cmd_info is valid
disp(cmd_info);

This code generates the following output:

************************************************************
*        TANGO ERROR STACK         
************************************************************
- ERROR 1
   |-reason.....API_CommandNotFound
   |-desc.......Command dummy not found
   |-origin.....Device_2Impl::command_query_2
   |-severity...Error (1)
- ERROR 2
   |-reason.....command_query failed
   |-desc.......failed to execute command_query on device tango/tangotest/3
   |-origin.....TangoBinding::command_query
   |-severity...Error (1)
***********************************************************

//=============================================================================
// 4 - Compiling
//=============================================================================
4.1 - Required Software (any platform)

In order to compile the project you need:
- the TANGO-5.x library
- the omniORB-4.0.5 and omniThread-3.0 libraries
- <mex> and <mx> matlab MEX-file support libraries
  - on Linux :
      $MATLAB_ROOT/bin/glnx86
  - on win32 :
      .lib in %MATLAB_ROOT%\extern\lib\win32\microsoft\msvc6
      .dll in %MATLAB_ROOT%\bin\win32

4.2 - Under Windows (tested on Win2K Pro - Visual C++ 6.0)

- Open the project file (TangoBindingForMatlab.dsw)

- In <Project::Settings::C/C++::Preprocessor::Additional include directories>,
  modify the paths to point to your local TANGO and omniORB header files. Add
  the path to the Matlab header files <YOUR_LOCAL_MATLAB_DIR\extern\include>.
  Also add the paths to both omniORB and TANGO header files.

- In <Project::Settings::Link::Input::Additional library path>, modify the paths
  to point to your local TANGO and omniORB libraries.  Add the path to the
  Matlab libraries: <YOUR_LOCAL_MATLAB_DIR\extern\lib>. Also add the paths to both
  omniORB and TANGO libraries.

- In the project <Resource files tree>, replace the file <mexversion.rc> with
  your local copy (normally located in <YOUR_LOCAL_MATLAB_DIR\extern\include>)

- Build the MEX-file

- If the build succeeded, the MEX-file <tango_binding.dll> is located in the
  <mex-file> directory.

4.3 - Under Linux (tested on RH-Linux - gcc 3.2.2 or higher)

- Sorry, there is no automake/autoconf macros (contributions are welcome). 
  The makefile must be modified by hand but the modification should be  
  straightforward. Define _MATLAB_R12_ (i.e. add -D_MATLAB_R12_ to your
  CFLAGS if compile this binding for Matlab R12).

- Edit the Makefile and modify CORBA_BASE, TANGO_BASE and MATLAB_BASE according
  to your local configuration.

- Open a terminal and type <make> to build the MEX-file

- If the build succeeded, the MEX-file <tango_binding.mexglx> is located in the
  <mex-file> directory.x

4.4 - Solaris (native c/c++ compiler)

- A successfull Solaris native compiler build has been reported. For this
  platform, you have to modify the Makefile in order to adapt the compiler
  options.

//=============================================================================
// 5 - Generating standalone TANGO application with the Matlab Compiler
//=============================================================================

  We successfully build TANGO oriented standalone applications from Matlab .m
  files using the Matlab Compiler under both Windows and Linux. The application
  use the binding as a shared library to access the TANGO devices.

- Buy :-( , install, and configure the Matlab Compiler toolbox
- Write your TANGO application in pure .m code (e.g. myapp.m)
- At Matlab prompt type: mcc -g -p -v myapp.m
- Run the generated binary myapp
- Deploy anywhere without runtime license
- Magic, isn't ?


