Install Instructions

CODA 2.6 Installation Notes (August 2008)

1. UNPACKING THE DISTRIBUTION

The CODA distribution should be unpacked under a common directory (e.g. /usr/local/coda/2.6). This includes the SunOS and/or Linux, common, cMsg, afecs and VXWORKSPPC55 (vxWorks 5.5) directories. The x86-liunx distribution should be put in its own directory (e.g. /usr/local/gnu/x86-linux). The distribution is not required to go in a "/usr/local" partition.

There is a hidden setup script (i.e. /usr/local/coda/2.6/.setup that should not have to be changed other than to provide alternative default directory paths if certain ENV variables are not set. This is the general CODA setup script. It sets paths and environment variables necessary to use CODA. There is an example User setup script (in examples - "dosetupcoda26) that you can copy into your own home directory. It will need to be modified (i.e. hostnames, user specific paths) but it is necessary for setting user specific environment variables. Make sure it is executable as well, or simply imbed the code in your .cshrc . One should note that the User script will actually call the generic script provided in the distribution.

2. SETTING YOUR ENVIRONMENT

One should add the path to the cross compilers into his .cshrc as well as set certain environment variables not set in the setup scripts:

Define the CODA root directory for example:

     setenv CODA     /usr/local/coda/2.6

Set up to use PPC cross compilers for example

     set path = ( $path . /usr/local/gnu/x86-linux/bin)

At this point make sure that the information in your User setup script is correct. Then after logging in the user needs only to execute his setup script to initialize the environment for running CODA (i.e. source dosetupcoda26).

3. SETTING UP MSQL DATABASE

CODA uses an mSQL database to store component status and run configuration information. The information stored there is dynamic during the operation of any coda components. Communication is accomplished through a mSQL deamon running on the database host computer. This daemon ("msqld") once started should be left running in the background. It is often useful to have it started automatically when the host machine is booted.

The default mSQL database directory is $CODA/common/rcdb. Within this directory multiple databases can be created by the same or different users. The environment variable EXPID (in the dosetupcoda26 script) is set to the database name to be used. The env variables MSQL_TCP_HOST and MSQL_HOME are set to the msqld host name and default directory respectively. The User need only start the msqld running on the host after making sure these variables are set correctly.

   Note: The msqld should NOT be started and run as root. Second, the directory $MSQL_HOME must be
              writable by the owner of the "msqld" process.

There are two utilities with CODA for editing/creating mSQL databases. These are cedit and dbedit. cedit is the more user friendly tool that can be used to create a new CODA database, and add CODA components/run configuration information. dbedit is a general table editing tool that is useful for modifing existing databases, but in the wrong hands can easily corrupt a database.

  Note: A database with a least one run configuration must be created before any coda components
        can be started up.

More details on transfering an existing msql database can be found here.

4. JAVA RUNCONTROL ( The "Platform" )

With the msql deamon running, now all components (including run control) can be started up. The main experiment control server that must be running is a JAVA application called "rcplatform" (in $CODA/afecs/1.0/bin) The Platform contains the intelligent agent framework as well as the new CODA messaging (cMsg) server. It can be started up in a shell/window with no arguments (as long as $EXPID, $MSQL_TCP_HOST have been set). It does NOT have to be started on the same host as the msqld is running, and one does not have to specify which host (via an ENV variable) on which you choose to run it. However, the user must make sure that a directory is specified for the Platform database to reside (called $COOL_HOME). A default example COOL database is provided for the User in the "examples" directory (cool_db_example.tar). One can unpack this database in a prefered location, and then change the setup scripts to point $COOL_HOME to this diectory. The Platform should be left running and the user does not have to interact with that process again. Only one rcplatform should be active for a given $EXPID.

The Run Control GUI is also a JAVA application - "rcgui" (in $CODA/afecs/1.0/bin). It can be run from any host, and one can run multiple copies on multiple hosts. It can take several arguments (see the -h option), but only 1 is required. That is the -name option. Every rcgui must have a unique name:

    % rcgui -name RC1

From the GUI menus the user can access/change various options, or bring up component messaging browsers etc... One important feature that the User must do the first time he runs a particular configuration (and ANY time there are changes to that configuration) is execute the "Translate DB to COOL" command in the "Control" menu. This will take the msql info and create an appropriate RDF file in $COOL_HOME for the Platform to use. Again, anytime that cedit or dbedit are used to change the run Config in the msql DB then the user must update the COOL DB (always with the "Translate" menu option).

If the Platform is ever shutdown (or killed) for some reason, all rcgui processes will have to be killed and restarted as well. All CODA components should NOT have to be restarted. They should be able to reconnect after the Platform is started again.

5. STARTING CODA COMPONENTS

If you wish to startup a component interactively (for debugging, monitoring etc...) execute one of the following commands in an xterm window:

For a CODA ROC:

     % coda_roc -i -s ?session? -n ?rocname? -t ROC

For a CODA Event Builder

     % coda_eb -i -s ?session? -n ?ebname? -t CDEB

For a CODA Event Recorder

     % coda_er -i -s ?session? -n ?ername? -t ER

The -i starts and interactive Tcl shell. The -s is followed by the Session name. The -n is the name of the Component, and the -t is the object Type.

Starting the ROC or TS component on vxWorks hosts are done a little differently, but example boot scripts for these hosts can be found in the "examples/boot" directory.

6. COMPILING A READOUT LIST

In the subdirectory "examples/crl" there is a set of example readout lists that can be compiled with the CODA makelist utility (this requires that the x86-Linux cross compiler package be installed if one wishes to compile readout lists for PPC vxWorks targets). The only ROL appropriate for use with a Solaris/Linux based ROC is test_list.crl. One can compile it with the command:

                    makelist test_list.crl native

If compiling for VxWorks targets then:

                   makelist test_list.crl ppc -mlongcall

This creates an object (.so or .o) that will be downloaded to the ROC when the User selects download from the rcgui button panel. It contains user code to be executed during transitions and triggers. The "-mlongcall" option for ppc compilers is necessary for target VME CPUs with more than 32MB of RAM