Documentation

This page provides information for CSS people who develop, install and maintain CSS.

End-user documentation is provided as online help within CSS (Menu Help, Help Contents).

For developer information, including source code, mailing list etc. see

- Preferences - Un-packing JARs - Rebuilding - Message Log - Authentication - Archiver - Alarms - JMS -

Preferences, non-SNS Use

The SNS CSS Office applications are pre-configured for the SNS office network, while other packages might have no specific settings.

For use at your site, you might have to change the Preferences for at least CSS/Core/EPICS and the Data Browser to suit your needs. While you can do that via the menu item CSS/Preferences for each Workspace, system administrators can configure the default settings and additional parameters by editing the files configuration/config.ini and plugins/org.csstudio.*.product_*/plugin_customization.ini of the downloaded CSS application.

Un-packing Plugin JAR Files

In a product, most Eclipse/CSS plugins are jar files in a plugins subdirectory of the product, for example org.csstudio.basic.epics.product_1.0.0.jar, i.e. the name of the plug-in is followed by a version number and has a ".jar" extension.

In order to view the content of the plugin and maybe edit configuration files in there, it is possible to replace the jar file with its extracted content. On Linux/OS X:

mkdir org.csstudio.basic.epics.product_1.0.0
cd org.csstudio.basic.epics.product_1.0.0
unzip ../org.csstudio.basic.epics.product_1.0.0.jar
rm ../org.csstudio.basic.epics.product_1.0.0.jar

Note that the directory has the same name as the jar file except for the ".jar" extension, and we remove the original jar file after unpacking its content.

Rebuilding from Sources, Developing For Eclipse/CSS

A source snapshot for the SNS versions of CSS is available on the Products page. The main CVS repository at at DESY.

Ideally, you should have enough experience with developing Eclipse RCP applications to the point where all you need to know is this:

The short recipe is this:

  1. Get the Sun Java SDK. Not just a JRE, not a non-Sun-SDK.
  2. Install the Eclipse 'RCP' IDE from http://www.eclipse.org/
  3. Check which compiler the IDE is using. This is twofold:
    1. Workspace Default compiler.
      With Eclipse 3.5, it's configured under Preferences, Java, Installed JREs.
    2. Per-project (per-plugin) setting.
      In the Navigator or Project Explorer, you can right-click on each plugin, select Properties, Java Build Path, Libraries Tab, JRE System Library Setting, "Edit" and then select either the "Workspace default..." or a specific setting for this plugin.
    My preference is to configure all plugins to use the Workspace default, since this allows me to select the JRE that's used to compile all plugins via the workspace default.
    It might also be a good idea to develop the code with the latest SDK available, but compile it with for example Java 1.5 so that it will still run on older installations.
  4. Unpack the sources, "Import" them into the workspace
  5. Open one of the *.product files, follow the info in the "Exporting" section of the product file viewer/editor.

For more on RCP refer to books like the Addison-Wesley offerings "Eclipse Rich Client Platform: Designing, Coding, and Packaging Java Applications" by Jeff McAffer and Jean-Michel Lemieux or "Eclipse Plug-ins" by Eric Clayberg and Dan Rubel. For more on CSS specifics, contact the CSS developers.

RDB Message Log

CSS Tools can send log messages (warnings, error information) to a JMS server, from which other CSS tools can then log them to a central relational database (RDB) log.

Authentication and Authorization

CSS supports Auth. & Auth., which is especially used in the alarm system GUI.

RDB Channel Archiver

Upgrade of the Channel Archiver, where the maintenance of the custom binary data and index files became overwhelming. The new system in short:

Details:

BEAST

The Best Ever Alarm System Toolkit as used by the SNS.

JMS Server

The CSS message log and the Best Ever Alarm System Toolkit use a Java Message Server. Specifically, the Apache ActiveMQ implementation of JMS. Download it from http://activemq.apache.org. In principle you can just unpack the ActiveMQ package from the Apache web site, then

   cd apache-activemq-*/bin
    ./activemq

You might want to copy its default configuration file, conf/activemp.xml into something like my_activemq_setup and then use that configuration file:

   ./activemq xbean:file:/path/to/my_activemq_setup.xml

That way you can disable things that you don't need, like the web monitor, or enable HTTPTransport to allow tunneling though web proxies. Markus Möller (DESY) suggested disabling the "multicast" option in the "networkConnectors" section to prevent multiple JMS servers from magically finding each other and causing more confusion than good.

When you configure CSS tools to use your JMS server, it's suggested to use the "failover:" URLs:

 failover:(tcp://your_jms_host:61616)

will allow clients to re-connect automatically after network problems. Avoid multi-host failover as follows unless you specifically configured those JMS hosts for master/slave failover or message forwarding:

 failover:(tcp://first_jms_host:61616,tcp://second_jms_host:61616)
kasemirk@ornl.gov