		TANGO source code release version 6.0 - README
		================================================
			Jens Meyer (meyer@esrf.fr)
			------------------------i-------
			        25/06/2007


TABLE OF CONTENTS
-----------------

 1 - Introduction
 2 - What's inside
 3 - Prerequisites
 4 - Installing
 5 - Compiling
 6 - Running
 7 - Updating from previous Tango releases
 8 - Documentation
 9 - Remarks
10 - Questions
11 - URL
12 - Changes


1 - INTRODUCTION
----------------
This is the README for the TANGO source code release. TANGO is a
toolkit for building object oriented control systems based on CORBA. 
TANGO is a joint effort of the ESRF, ELETTRA, ALBA and SOLEIL synchrotron 
radiation sources.

This source code release is based on the latest version of TANGO 6.0
and is intended for Unix platforms. A binary version for Windows of TANGO 
is available. The source code contained in this package 
runs on Windows but the Makefile don't.

Tango 6.0 is compliant to the 64 bit architecture.

This package is forseen (and was tested) to run with omniORB4.1 and
Java 1.5

The Pogo application in this package can generate source code
for C++, Java and Python device servers.

The database server delivered with this package do not force the MySQL
user to be root any more. You have to use the my.cnf configuration files
or the MYSQL_USER and MYSQL_PASSWORD environment variables to specify
the MySQL account to be used by the database server.

In the case of upgrading an alreay running Tango system, please follow
the instructions in the chapter UPGRADING FROM PREVIOUS TANGO RELEASES.


2 - WHAT'S INSIDE
-----------------

This source code release contains :

(1) Tango C++ library source files and java library and application jar files

(2) The Tango database device server source files (using mysql) and the
    MySql configuration files.

(3) The Jive application. 

(4) The Astor application and its associated Starter device server source files.

(5) The Pogo application.

(6) The tg_devtest application

(7) A test device server called TangoTest with its source files

(8) The atk graphical toolkit for writing tango applications in java

(9) The atkpanel application as a generic test client

(10 The atktuning application for tuning attributes in a device

(11) The logviewer application for visualising logging messages

(12) The DeviceTree application to display tango device attribute and/or command

(13) The atkmoni application to monitor scalar attribute values in time

(14) The jdraw synoptic editor to create synoptic applications

(15) The synopticAppli to run and test synoptics created with jdraw

The Jive application is a Tango database browsing tool written in Java. It also
allows device testing. Its documentation is at

	http://www.esrf.fr/computing/cs/tango/tango_doc/tools_doc/jive_doc/index.html
	
The Astor application is also a Java application. With the help of the Tango
starter device server, it allows full remote Tango control system administration.
Its documentation is at :

	http://www.esrf.fr/computing/cs/tango/tango_doc/tools_doc/astor_doc/index.html
	
The Pogo application is a graphical Tango device server code generator.
Its documentation is at :

	http://www.esrf.fr/computing/cs/tango/tango_doc/tools_doc/pogo_doc/index.html
	
tg_devtest is a device testing application for device server which do not
use the database. It is a sub-part of Jive. 

3 - PREREQUISITES
-----------------

Before compiling and installing TANGO you need to install :

(1) omniORB available from http://sourceforge.net/projects/omniorb 
    (version >= 4.1)

(2) mysql available from http://mysql.org (version > 3.22)

(3) omniNotify release 2.1 available from http://omninotify.sourceforge.net/nfy_download.html
    
    Remark : omniNotify is an implementation of the CORBA Notification
             Service. It is not mandatory to run Tango and therefore
	     it's installation is not checked by the "configure" script.
	     If you don't install it, it will not be possible to communicate
	     between client applications and devices using the Tango event
	     system. Only the synchronous and asynchronous way of communication
	     will be possible.
	     
(4) doxygen available from http://www.doxygen.org

    Remark : doxygen is not mandatory to run Tango. It is just used by our code
             generator (called Pogo) to automatically generates some part of 
	     the Tango device server documentation. If you don't install it,
	     this part of the documenetaion will simply not be generated.
	     But in all cases, some HTML pages documenting Tango device server
	     will allways be generated.

Also check the tools you are using

(1) If you are using gcc, you need to have gcc release 3.2.0 or above. You can
    download gcc from http://gcc/gnu.org

(2) Only java release 1.5.0 or above is supported, you can download java from
    http://java.sun.com/j2se (See chapter 4, Java sub-chapter)


4 - INSTALLING
--------------

Once you have installed the packages in prerequisites you can think
about configuring and compiling TANGO. 

To configure TANGO you need to tell it where to find omniORB and
mysql (if it is in a non-standard place) and where to install
TANGO.

mysql
-----
Make sure mysql is running before doing configure.
Also check that the mysql client (called mysql) is in your path.
If you are not running the configure script on the same host
where the mysql server is running, use the "--with-mysql-ho" configure
option. The configure script will try to connect to the
MySql database. Make sure that privileges are granted to
the user used by configure running on the host where you
run configure. The configure options "--with-mysql-admin"
and "--with-mysql-admin-password"
allow you to select which MySql user configure will use.
The default is "root" without a password.


Database server, mysql and libz
-------------------------------
Depending on how MySql has been installed, the Tango database
server may need the compress/uncompress library (called "libz").
By default, configure try to find this compress/uncompress stuff.
If you don't need it, use the configure "--without-zlib".


Java
----
Tango arrives with many Java applications. Each java applications has
its own script (in $prefix/bin) where the CLASSPATH is set before 
starting the java interpreter. These scripts will be modified by the
configure script to set a correct path to the java interpreter found in
your PATH when configure was run. You can also use the "--with-java=xxx"
to define a path to the java interpreter.
It is not mandatory to find the java interpreter in your PATH. You can use 
the "--without-java" configure option to build Tango. This will result in
an incorrect substitution in scripts. In such a case, you will have to
manually do the substitution in scripts located in $prefix/bin.

doxygen
-------
Doxygen is a documentation generator from C++ source files. It is used by the
Tango code generator (called Pogo) to generate Tango device server documentation.
The script used to start Pogo will be modified bt the configure script to set
a correct path to the doxygen command found in your PATH when configure was
run. You can also used the "--with-doxygen=xxx" to define a path to the
doxygen command.
It is not mandatory to find the doxygen command in your PATH or to use the
"--with-doxygen" configure option to build and run Tango. This will only prevent
some part of Tango device server documentation to be generated by Pogo.


You can type "configure --help" to get a print of all the options
supported by the configure script.

Here is an example of running configure for TANGO telling it where
to install (--prefix) TANGO and where omniORB is installed:

cd $directory_where_tango_has_been_installed
mkdir build
cd build
export CC=gcc
export CXX=g++
../configure --prefix=/home/tango/release/install_dir_linux \
	--with-omni=/segfs/tango/ORB/omniORB4.1.0/suse82

Here is an example running configure on Solaris telling it where
to install TANGO, where omniORB is installed and where mysql is
installed :

cd $directory_where_tango_has_been_installed
mkdir build
cd build
export CC=/opt/SUNWspro/bin/cc
export CXX=/opt/SUNWspro/bin/CC
./configure --prefix=/users/tango/release/install_dir_sol \
	--with-omni=/segfs/tango/ORB/omniORB4.1.0/solaris9_CC \
	--with-mysqlclient-include=/segfs/tango/database/solaris9/include/mysql \
	--with-mysqlclient-lib=/segfs/tango/database/solaris9/lib/mysql
	
During the configure procedure the access to mysql is tested. Please prepare
your my.cnf (mysql configuration file) or use the configure options
               --with-mysql-admin
               --with-mysql-admin-password
					--with-mysql-ho
to specify the access to the mysql database.
The default access as root without any password is no longer available!

	

5 - COMPILING
-------------

Once configure has run successfully you can compile and install the
executables, include files, libraries and scripts. Do this by typing :

make all

make install


6 - RUNNING
-----------

To test wether the TANGO build worked do the following :

(1) start the database on port 10000 by typing :

    TANGO_INSTALL_DIR/bin/DataBaseds 2 -ORBendPoint giop:tcp::10000
    
	 Specify the mysql account to be used by the database server.
	 Two possibilities are available:
	 	- set the following environment variables to the account and 
		  password to be used
    
           MYSQL_USER to specify the mysql login name
           MYSQL_PASSWORD to specify the password
			  
		- configure the mysql client with the mysql configuration 
		  file my.cnf
		  		
				[client]
				user      = [mysql login name]
            password  = [password]

(2) Configure the TANGO_HOST environment variable with the hostname the
    database server is running on and the port number used.

    setenv TANGO_HOST hostname:10000

(3) start the test device server tangoTest :

    TANGO_INSTALL_DIR/bin/TangoTest test

(4) start jive by typing for example :

    TANGO_INSTALL_DIR/bin/jive
    
    (See chapter 4 java sub-chapter to check the jive script) 

(5) test your device using the test device in jive

(6) write new device servers using pogo :

    TANGO_INSTALL_DIR/bin/pogo

    (See chapter 4 java sub-chapter to check the pogo script) 


7 - UPDATING FROM PREVIOUS TANGO RELEASES
-----------------------------------------
Starting with release 4, Tango needs the event table in its MySQL database.
If you are upgrading from release 4 or older, create first the event table 
in your MySql database. You can find the event table definition in
<install_dir>/share/tango/db/create_db.sql.

Updating from of Tango 5.3, you should update the corrected
indexing of the database tables. Compare with the file 
<install_dir>/share/tango/db/create_db.sql. 
Correcting the indexing and installing a cache for MySQL will speed-up
requests on a growing database. An example file for the MySql set-up
is available at
<install_dir>/share/tango/db/my.cnf

Updading from all releases before Tango 5.5.2, implies a change of the database
schema to run the database server. New history tables needs to be added. 
The existing database tables will not be affected!

Please follow the instructions:

Launch the mysql client
	mysql -u[user] -p[password]

Check if the database scheme has already history tables
	mysql> show tables;

If the scheme already has history tables, you should see the 6 following tables
	+--------------------------------+
	| Tables_in_tango                |
	+--------------------------------+
	| ...                            |
	| history_ids                    |
	| property_attribute_class_hist  |
	| property_attribute_device_hist |
	| property_class_hist            |
	| property_device_hist           |
	| property_hist                  |
	| ...                            |
	+--------------------------------+

If you don't have the history tables:
Use the db_init_history program to create/initialise history tables.
This program will create and fill the history tables with the current 
dababase property values (to initialize the first value of the 
property history). This tool does not affect old tables.
Even if you run this tool, you will still be able to start
an old release of the database server afterwards.

	db_init_history [user] [password]

Now, you should be able to start the new database server on port 10000
	
	TANGO_INSTALL_DIR/bin/DataBaseds 2 -ORBendPoint giop:tcp::10000 -v

If your database server stops with the following exception 
you don't have the correct database shema.

	Received a CORBA::Exception
	Tango exception
	Severity = ERROR
	Error reason = DB_SQLError
	Desc : Failed to query TANGO database (error=Table 'tango.property_device_hist' doesn't exist)
	Origin : DataBase::check_history_tables()


To test if the data base server is working fine, you can launch jive
	TANGO_INSTALL_DIR/bin/jive
	
	
Udating from all former releases, need to specify the mysql account 
to be used by the database server. The account root without password
is no longer used as default!
Two possibilities are available:
	 	- set the following environment variables to the account and 
		  password to be used
    
           MYSQL_USER to specify the mysql login name
           MYSQL_PASSWORD to specify the password
			  
		- configure the mysql client with the mysql configuration 
		  file my.cnf
		  		
				[client]
				user      = [mysql login name]
            password  = [password]


8 - DOCUMENTATION
-----------------

Don't forget to READ THE MANUAL (in doc/tango_6.0.pdf) !

9 - REMARKS
-----------
TANGO 6.0:
Tango 6.0 is a major release, because it uses omniORB 4.1 which is
a major release of omniORB. The code generated from the with the IDL
compiler is not compatible with the code gernerated with omniORB 4.0.x!
To avoid any confusion with new and old libraries we decided to
make also a major Tango release.

Recompiling a device server with Tango 6.0 and omniORB 4.1 means 
recompiling ALL classes of the device server. You need to work with
coherent include files.


TANGO 5.5.2:
The new database server keeps by default a history of the last 10 changes
for every property value. To configure another history depth, the property
"historyDepth" of the database device can be used. 
See the README.txt file in share/tango/db for more information.
With Jive it is possible to view the history of a property value or to 
restore an old value. Go to Tools menu and choose "Database history".
To view property values, the wildcard * can be used.

TANGO 5.5:
The new version of the database server has increased the limit of
open file descriptors from 256 to 1024 (for UNIX platforms!).
The command line option "-maxFile" allows to change this configuration.

When using events with Tango, two diagnostic tools are available.
The astor application allows to configure and test the available
events. Under the view menu open the Device Browser. Choose and open 
your device. Right click on an attribute to subscribe and configure 
events for this attribute.
The atkpanel applications offers under the view menu a diagnostic 
panel which shows the availability of events and some statistics.


10 - QUESTIONS
--------------

You will definitely have some ! Send questions to tango@esrf.fr.

11 - URL
--------

Visit the TANGO website http://www.tango-controls.org for online 
documentation, news and to download add-on packages.


12 - CHANGES
------------

See the file TANGO_CHANGES to get an overview of all modification
between the different Tango versions.
