/*******************************************************************************
 *	overview.doc	Main overview page for LibTms
 *******************************************************************************
 */
/**
\author Dr Terry Barnaby
\version 1.0.0
\date 2007-10-09

\mainpage

\section Introduction
This document covers the BEAM LibTms software API for the CERN trajectory
measurement system.
This API provides the ability to control and receive data from the TMS System.
The API is an object orientated API implemented in 'C++'  with a number of
object classes. The API operates over a network type interface using an RPC
type mechanism.

The LibTms API makes use of the BEAM standard class library.
The BEAM standard class library provides a small set of low level 'C++' classes for strings,
lists and system interface functions. There is some brief information on the
BEAM class library later on in this page.

\section Overview
Generally users of the system are only concerned with the top level, System
Controller API. This is the API that control and data gathering clients use to
control and gather data from the system. The System Controller API (TmsApi) is
implemented using a simple, object orientated, RPC mechanism. Two main objects,
the <b>Tms::TmsControl</b> and <b>Tms::TmsProcess</b> objects, provide the full API.

The TmsApi has been
developed using the BOAP (BEAM Object Access Protocol). This provides a simple
but powerful Object Orientated RPC mechanism. The TmsApi is written in a high
level interface definition language (IDL). The bidl tool generates the client
and server side 'C++' interface and implementation files for the API. These are
then provided as a set of 'C++' header files and a binary library file for the
clients to link to. The BOAP system employs a simple BOAP name server process
that provides a translation between object names and IPAddress/Socket numbers.
The BOAP name server runs on the System Controller. More information on the BOAP
system can be found in the libBeam documentation.

There are two main Objects that are used by clients of the TMS API.
They are the <b>Tms::TmsControl</b> and the <b>Tms::TmsProcess</b> objects.
The <b>Tms::TmsControl</b> object is used for system configuration, testing and diagnostics.
The <b>Tms::TmsProcess</b> object is used for normal clients for Proton Synchrotron (PS) Cycle information 
configuration and data access.
There is some example client code in the tmsExamples of the source code and displayed
later on this page.
These objects communicate through a network connection with the TmsServer process running on the TMS System
Controller.
The TMS System Controller operates as a multi-threaded process and can communicate with
multiple clients simultaneously.

The TMS system takes most of its system timing
signals from digital timing lines connected to the TMS rack hardware. The only
timing information that external software needs to supply is the next cycle
number and cycle type information. The cycle number is a 32bit unsigned number
identifying the next Proton Synchrotron (PS) machine cycle. The cycle type is
and ASCII string defining the type of BEAM present in the PS machine. The cycle
type defines a set of state/phase tables to be loaded in order to measure the
BEAM in the machine.
The CERN client software needs to provide this information by calling the
setNextCycle() function before the next PS cycle is initiated.

The TMS system keeps a library of state/phase tables indexed by the cycle
type. These are loaded into the individual PUPE engines FPGA's during the
CYCLE_STOP to CYCLE_START period. The API provides the <b>setControlInfo</b> and
<b>delControlInfo</b> calls to maintain this database.

A client would generally use the <b>Tms::TmsProcess</b> object for its
interface to the TMS system. It would use call getData() to fetch the
required data from the system. There is also an event based data interface
implemented using the requestData() call and dataEvent() event call.

Each of the TMS API calls return an error object. If there is an error,
an appropriate error number will be given together with an ASCII string describing
the error.

\section libbeam BEAM class library
The BEAM class library implements some basic low level classes and is used by
the TMS API implementation itself.
The main class functionaly includes:
- BString - A simple string class
- BList - A templated list class
- BArray - A templated array class
- BError - An error return class containg an integer and string
- BSocket - A Network socket access class
- BThread - A thread implementation class
- BPoll - A file descriptor event polling class
- BMutex - A mutex lock
- BRWLock - A read/write lock
- BSema - A semaphore
- BCondInt - An integer condition class
- BFile - A simple file access class
- BDir - A simple directory access class
- BEntry - A name/value pair list class
- BNameValue - A name/value pair class
- BRtc - A realtime clock
- BTimer - A simple timer class
- BUrl - URL access class

\section TmsApi Examples
There are some examples of client applications using the TmsApi in the
<b>tmsExamples</b> directory of the source code.
A simple Data Access client example is listed bellow:
\include tmsDataClient1.cpp

A simple Control client example is listed below:
\include tmsControlClient1.cpp

A simple Control client to set the next cycle information example is listed below:
\include tmsControlClient2.cpp

*/