			TANGO binary distribution 
			=========================
			ALPHA release 1.0 6/4/2001
			--------------------------
                                  by
			  E.Taurel + A.Gotz
			
		
WARNING : This distribution has only been tested on Linux Suse 6.4 and 7.1
          (it should work on other distributions of Linux assuming they have 
	  the necessary C, C++ and Java libraries i.e. any recent distribution)

I - Introduction
----------------

TANGO is a package for building CORBA distributed objects. It uses the
CORBA IIOP protocol for all network communication. It has a database 
for storing device network information (IOR in CORBA parlance) and
device related properties. The main use of TANGO is for wrapping and/or
implementing control devices and exporting them onto the network. 
The advantages of TANGO compared to CORBA are that it provides a 
unified development model and interface to all devices and it hides 
the CORBA details. TANGO also provides a database for storing device
related information permanently, a graphical tool for developing and
maintaining TANGO device servers (pogo), generic tools for accessing
TANGO device from a web browser (Jive) and easy to use client api's
for C++ and Java. TANGO presently only supports synchronous communications.
Asynchronism will be added in a (not too distant) future release.

The present release of TANGO is a binary release for Linux (tested on 
SuSE 6.4 and upwards) plus source code. The next release will be a 
source code only release.

II - Software needed
--------------------

In order to run the Tango control system, you need mysql database. 
For Linux users this is normally part of your distirbution. If you
don't have it or want to upgrade it however download it from 

	http://www.mysql.com.

Tango has been developped using mysql release 3.22.32 (default with Suse 6.2)
but it should work with newer releases.

Tango is only supported with gcc release 2.95.2 (default with Suse 6.4)

Jive (A generic Tango device menu) needs java 1.1.7 (default with Suse 6.4)

Jive (servlet release) needs Apache 1.3.12 (default release with Suse 6.4)

Pogo (the device server generator) has some editing features. You can choose
between vi or nedit as editor. nedit can be downloaded from 

	http://www.nedit.org

Pogo needs java 1.2.2 or above. In order to have both Jive and Pogo, you must
have on your computer java 1.1.7 (For Jive) AND 1.2.2 (for Pogo)


III - Directories
----------------

script - Some scripts to start tango control system tools.
         You have to update them in order to reflect your file system structure.
	 tango : To start/stop the control system itself
	         (change at lines 56/57 to update your directory tree)
	 JiveDb : To start Jive database control as stand-alone application
	 JiveDev : To start Jive device generic menu as stand-alone application
	 pogo : To start the Tango device server code generator
	 create_dbase : A script to create database tables

cppserver - Directory for c++ device server
cppserver/device - source code for the TANGO device root class
cppserver/dbase - source for the TANGO database server
cppserver/dbase/bin - database server executable

include - The tango include files
lib - The tango libraries
java - The Tango jar file

ORB - The ORB product used by Tango. It is an ORB developped by a company called
      OOC. Because it cannot be distirbuted as part of TANGO you need to 
      download the latest version and compile it. To download go to 
      
      	http://www.ooc.com

      and download Orbacus. TANGO is based on V4.0.3 but more recent versions
      should work as well.

ORB/include - copy the Orbacus include files here
ORB/lib - copy the Orbacus libraries here
ORB/java - copy the Orbacus jar file here

JTC - The thread product used by Tango. This product also comes from the OOC
      company. Download it from OOC. TANGO has been built with release 1.0.12
JTC/include - copy the JTC include files here
JTC/lib - copy the JTC libraries here

doc/manual/programmer - The Tango device server programmer's manual
doc/api - documentation for the TANGO C++ and Java api's
doc/guides - documentation for the TANGO Database server

httpd - Directory for Jive running in a browser (servlet mode)
httpd/conf_ex/xx - Example of how the Apache WEB server is configured in order to 
                   run correctly. You may have to adapt these file to reflect
		   your directories tree
httpd/httpd - The tree necessary for Jive running as servlet

tools/pogo - The pogo directory tree
tools/pogo/doc - Pogo documentation directory tree
tools/pogo/doc/bin - The doc++ tool used by Pogo to generate device server 
		     HTML pages from the C++ .h files
tools/pogo/doc/pogo - Pogo doc
tools/pogo/tools/jar - Pogo jar file
tools/pogo/tools/pogo/templates - The template files used by pogo to generate
                                  device server


IV - Install Tango core
------------------------

1 - Install mysql (if not already installed)

2 - Start mysql daemon processes (using safe_mysqld)

3 - Create Tango database tables
    Run mysql interpreter with the script stored in script as 
    mysql root user
    		mysql -u root < ./create_dbase
    This script grant privileges to all users on "localhost".
    It will also create one database called tango with 8 tables called 
    
	attribute_class, 
	device, 
	property, 
	property_attribute_class, 
	property_attribute_device
    	property_class 
	property_device
	server
    
4 - Define your TANGO_HOST environment variable. It must be of the form
    TANGO_HOST=<host>:<port>. The port chosen at the ESRF is 20000.

5 - Add the following directories to your LD_LIBRARY_PATH:
	tango/lib
	tango/ORB/lib
	tango/JTC/lib
	   
6 - Go to tango/cppserver/dbase/bin and start the database server
   	./DataBaseds 1 -OAport <port> [-v]
    The database is accessible via a classical Tango device called 
    		sys/database/1
    When the database server starts, it prints out five lines of text. The last
    line should be "Ready to accept request".
	
Note that the startup of mysql and the Tango database server is possible with 
the tango script located in the script/tango directory. Use it with "start" as
parameter to start Tango or "stop" to stop it. Copy it to /etc/init.d and add
it to run levels 3 and 5 to start it at boot time.


V - Install Jive as servlet
----------------------------

To support Apache and servlet, you need the JSDK and Jserv. You can find
two compatibles release of them in the directory tango/httpd/httpd

In all the examples given below, the computer is called "tango",
nd the tango.tar file has been installed in a directory called "/users/berruyer"
	      
1 - Install JSDK

2 - Install Jserv
     
    tango:/usr/local # tar xvzf /users/tango/httpd/httpd/ApacheJServ-1.1b3.tar.gz
    tango:/usr/local # cd ApacheJServ-1.1b3/
    tango:/usr/local/ApacheJServ-1.1b3 # ./configure
    tango:/usr/local/ApacheJServ-1.1b3 # make
    tango:/usr/local/ApacheJServ-1.1b3 # make install
   
3 - Configure Apache (take example in tango/httpd/conf_ex)
     
    tango:/etc/httpd # mv httpd.conf httpd.conf.orig
    tango:/etc/httpd # cp /users/tango/httpd/conf_ex/httpd.conf .

    tango:/etc/httpd/jserv # cp jserv.conf jserv.conf.orig
    tango:/etc/httpd/jserv # cp /users/tango/httpd/conf_ex/jserv/jserv.conf .

    tango:/etc/httpd/jserv # cp jserv.properties jserv.properties.orig
    tango:/etc/httpd/jserv # cp /users/tango/httpd/conf_ex/jserv/jserv.properties .

    tango:/etc/httpd/jserv # cp zone.properties zone.properties.orig
    tango:/etc/httpd/jserv # cp /users/tango/httpd/conf_ex/jserv/zone.properties .

    tango:/etc/httpd/jserv # cp /users/tango/httpd/conf_ex/jserv/zone_jive.properties .
    tango:/etc/httpd/jserv # cp /users/tango/httpd/conf_ex/jserv/zone_admin.properties .
    tango:/etc/httpd/jserv # cp /users/tango/httpd/conf_ex/jserv/zone_tesoperties .
 
4 - Update servlet configuration files to reflect your directory tree 

    Example : The following are the diff results between the updated file and 
    the origin distribution file
	      
    tango:/etc/httpd # diff httpd.conf /users/tango/httpd/conf_ex/httpd.conf
    557c557
    < DocumentRoot "/users/tango/httpd/httpd/htdocs"
    ---
    > DocumentRoot "/segfs/tango/httpd/htdocs"
    585c585
    < <Directory "/users/tango/httpd/httpd/htdocs">
    ---
    > <Directory "/segfs/tango/httpd/htdocs">
    1371c1371
    < DocumentRoot "/users/tango/httpd/httpd/htdocs"
    ---
    > DocumentRoot "/segfs/tango/httpd/htdocs"

        
    tango:/etc/httpd/jserv # diff jserv.properties /users/tango/httpd/conf_ex/jserv/jserv.properties
    58,59c58,68
    < wrapper.classpath=/users/tango/ORB/java/OB.jar
    < wrapper.classpath=/users/tango/java/Tango.jar
    ---
    > wrapper.classpath=/segfs/tango/ORB/JOB/unix/lib/OB.jar
    > wrapper.classpath=/segfs/tango/lib/java/Tango.jar

    tango:/etc/httpd/jserv # diff zone.properties /users/tango/httpd/conf_ex/jserv/zone.properties
    25c25
    < repositories=/users/tango/httpd/httpd/servlets
    ---
    > repositories=/segfs/tango/httpd/servlets



    tango:/etc/httpd/jserv # diff zone_jive.properties /users/tango/httpd/conf_ex/jserv/zone_jive.properties
    25c25
    < repositories=/users/tango/httpd/httpd/servlets/jive
    ---
    > repositories=/segfs/tango/httpd/servlets/jive


    tango:/etc/httpd/jserv # diff zone_admin.properties /users/tango/httpd/conf_ex/jserv/zone_admin.properties
    25c25
    < repositories=/users/tango/httpd/httpd/servlets/admin
    ---
    > repositories=/segfs/tango/httpd/servlets/admin


    tango:/etc/httpd/jserv # diff zone_test.properties /users/tango/httpd/conf_ex/jserv/zone_test.properties
    25c25
    < repositories=/users/tango/httpd/httpd/servlets/test
    ---
    > repositories=/segfs/tango/httpd/servlets/test

5 - Allow Apache (when not started by root user but by wwwrun user) to log
    messages (unscrew the file access protection)

    tango:/usr/local/httpd # chmod -R a+rw logs/
    tango:/usr/local/httpd #
    
6 - Restore links

    tango:~/tango/httpd/httpd/htdocs % ln -s Jive.html index.html
    tango:~/tango/httpd/httpd/htdocs % ln -s /users/tango/java/Tango.jar .

7 - Update tango database default computer in html pages

    This means replacing in "/users/tango/httpd/httpd/htdocs/Jive.html"
    and "/users/tango/httpd/httpd/htdocs/Database.html" all the
    occurence of tango by <host> (the host where the database server is running)

8 - Start Apache

9 - Start a WEB browser (IE or netscape)

10 - Connect to your Apache server (http://<host>)

11 - Play with the Tango WEB interface. You can access Jive by typing the name of
     the device you want to test in the device name window of the "Execute
     command on a device server" chapter of the Tango WEB interface.
    
    
VI - Install Jive stand alone applications
-----------------------------------------

Jive is also available as stand-alone applications. Two applications are 
available.  One is started by a script called JiveDev (in tango/script). 
This one is the generic device access menu. The second one is also started 
by a script called JiveDb (in tango/script). This is a Tango database interface.

These two simple scripts have to be customized according to your directory tree.

VII - Install Pogo
-----------------

Pogo is a device server code generator. It is a Java graphical application using
swing.

1 - Install JDK 1.2

2 - Update the script/pogo script to reflect your directory tree.

3 - Update the Makefile template for C++. It must be updated to reflect
    your directory tree. This template is in 
    tools/pogo/templates/cpp/Makefile.
    
Please, note that the generated Makefile must be used with gmake and started
by defining "linux=1"

	gmake linux=1 XXXX


VIII - Conclusion
-----------------

Maybe the most important thing :

		taurel@esrf.fr  +  goetz@esrf.fr !!!!!!!!!


		
Good luck
May the force be with you
Don't worry, there is a light at the end of the tunnel.
