//=============================================================================
// 			THE TANGO BINDING FOR MATLAB - RELEASE 1.1.0
//=============================================================================

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

Please send bug report, suggestion or comment to: 
nicolas.leclercq@soleil.u-psud.fr.

Have fun with TANGO under Matlab.
Nicolas.

//=============================================================================
// 2 - Compiling
//=============================================================================

NB: The <mex-file> contains a pre-build MEX-file for both Windows-2K
(tango_binding.dll) and RH-Linux-7.2 (tango_binding.mexglx).

2.1 - Required Software (any platform)

In order to compile the project you need:
- the TANGO-2.1.1 (or later) library (TANGO core library)
- the ORBacus libraries OB-4.1.1 and JTC-2.0.0 (CORBA implementation)
- the <mex> and <mx> libraries that come with Matlab-R12 (MEX-file support)

2.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 ORBABUS header files. Add
  the path to the Matlab header files <YOUR_LOCAL_MATLAB_DIR\extern\include>

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

- 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.

2.3 - Under Linux (tested on RH-Linux-7.2 - GCC 2.95.3)

- Sorry, there is no automake/autoconf macros (contributions are welcome). 
	The makefile must be modified by hand but the modification should be    
	straightforward

- 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.

//=============================================================================
// 3 - Installing
//=============================================================================

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. It is
recommended to permanently store these paths in your Matlab pathdef.m file
(Matlab Set Path... menu item).

//=============================================================================
// 4 - Using the TANGO binding under Matlab
//=============================================================================

4.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).

4.2 - Error Handling

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)
************************************************************
