/*******************************************************************************
 *	overview.doc	Main overview page for LibTms
 *******************************************************************************
 */
/**
\author Dr Terry Barnaby
\version 0.5.1
\date 2007-05-18

\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>TmsControl</b> and <b>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>TmsControl</b> and the <b>TmsProcess</b> objects.
The <b>TmsControl</b> object is used for system configuration, testing and diagnostics.
The <b>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 information. This is a 32bit unsigned number identifying the next Proton
Synchrotron (PS) machine cycle. The CERN client software needs to provide this
information by calling the setNextCycleNumber() function before the next PS
cycle is initiated.

A client would generally use the <b>TmsProcess</b> object for its
interface to the TMS system. It would use the setControlInfo() function to
configure the measurement settings for the next and subsequent PS machine
cycles. And then 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 a string describing the error.

\section libbeam BEAM class library
The BEAM class library implements some basic low level classes and is used by
the DdcServerAPI and the DdcServer 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

*/