%  Copyleft (c) 1997-2000 by Mark Koennecke at PSI, Switzerland.
%
%
%  This software is distributed in the hope that it will be useful,
%  but WITHOUT ANY WARRANTY; without even the implied warranty of
%  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%  GNU General Public License for more details.
%
%  You may already have a copy of the GNU General Public License; if
%  not, write to the Free Software Foundation, Inc., 675 Mass Ave,
%  Cambridge, MA 02139, USA.
%

\documentclass[12pt]{article}
\usepackage{epsf}
\setlength{\oddsidemargin}{-.1in}
\setlength{\evensidemargin}{0in}
\setlength{\topmargin}{0in}
\addtolength{\topmargin}{-\headheight}
\addtolength{\topmargin}{-\headsep}
\setlength{\textheight}{8.9in}
\setlength{\textwidth}{6.2in}
\setlength{\marginparwidth}{0.5in}

\begin{document}
\title{SICS Reference Manual}

\author{Mark K\"onnecke\\
  Labor f\"ur Neutronenstreuung\\
  Paul Scherrer Institut\\
  CH-5232 Villigen PSI\\
  Switzerland\\       
  Mark.Koennecke@psi.ch \\
}

\maketitle
\clearpage
\tableofcontents

\clearpage

\section{SICS Programmers Reference}
This document is mostly a boring listing of the interfaces and functions provided by
the SICS modules. In order to get an idea of what is going on, please look
at the SICS user documentation, the SICS manager documentation, and the SICS
programmer guide. 

{\huge Warning} This document serves as
internal document for SICS developers only. It has not been proofread to any
standards!

\section{Coding Practicalities}
\subsection{Files}
Any module or object has at least the following files associated with it:
\begin{description}
\item[.h] a header file with the external function definitions and
often a typedef for the object data structure. The idea is that object
data structures are exposed only where absolutely necessary. 
\item[.c] the implementation file. Often data structures are only
defined in here. 
\item[.tex] a latex file describing the module or object, its data
structures and its interface functions. To be included into this document. 
\end{description}
Quite often, there are further files:
\begin{description}
\item[.i] descriptions of internal data structures.
\item[.w] nuweb literate programming files. .w file contain a mixture
of latex commands and code. The idea is that the code is embedded with
the documentation. There are special commands to craete additional
output files suitable for a compiler. The .w files are processed by
the nuweb utility which will create tex documentation and code files
from it. In SICS this is used to document data structures and
interfaces and provide general information about each object. Then
.tex, .h and .i files are created by nuweb. The use of this facility is
recommended.  
\end{description}

\subsection{Building SICS}
This document describes how to build the SICS software and where to find it.
There are two sections: Building the SICS applications and building the Java
 clients. For both categories tarballs with all necessary files can be
 found in the /data/lnslib/src/sics directory. There are two tar files: 
 sics.tar which contains the sources for the SICS server and additional C or
 F77 applications and java.tar which contains the code for the Java clients.

\subsubsection{Building the SICS Server and Applications}
The first step is to untar the sics.tar file. As a result a directory sics 
 with several subdirectories will be created. These subdirectories are:
\begin{description}
\item[hardsup] contains David Madens and other hardware drivers.
\item[motor] contains the unix version of David Madens el734\_test program.
\item[doc/programmer]holds programming documentation for SICS. 
\item[doc/user] The html sources for the user documentation. Also everything 
 necessary for creating the printed documentation.
\item[bin] Holds the final binary files.
\item[tcl] Some Tcl helper code.
\item[doc/manager]The SICS managers documentation.
\item[difrac] The DIFRAC four circle diffraction subsystem.
\end{description}   
For most programs makefiles are provided. 
 Makefiles may need a little editing to correct the location of libraries. 
 All necessary headers should be available in /data/lnslib/include and the
 libraries in /data/lnslib/lib.
Building things within this hierarchy basically require to steps:
\begin{enumerate}
\item cd into the hardsup and difrac directories and type make in 
each. This builds required libraries for linking other applications.
\item cd into the directory of the program you wish to compile and type make.
For instance for building the SICServer, move into the main sics directory and
 type make. 
\end{enumerate}

\subsubsection{Building Java Clients}
Again the first step is the untaring of tha java.tar file. This creates a
 java subdirectory which holds several other subdirectories:
\begin{description}
\item[focus] contains files special to the FOCUS status display.
\item[lnsutil] a number of utility classes used by many SICs Java applications.
\item[misc] several older classes kept for the purpose of documentation.
\item[param] A package for building parameter displays.
\item[ptplot] A XY-plot package.
\item[sics] The Java command line client.
\item[tablelayout] a special AWT layout manager used in the NeXus network 
 Data Browser.
\item[varwatch] Files special to the Varwatcher client.
\item[cmapper] A package for mapping 2D-data arrays to colour pictures. Used
 for SANS.
\item[htmlv] A html display package used for the help system.
\item[lnet] Special network related utilities for the SICS Java applications.
\item[lnswidgets] custom user interface components.
\item[nndb] The NeXus Network Data Browser.
\item[powder] The powder status display for DMC and HRPT.
\item[sans] The SANS status display.
\item[spread] Another layout manager package.
\item[topsi] The topsi and general scan status display.  
\item[amor] The AMOR user interface program.
\end{description} 
Furthermore there are some Java source file in the main directory together 
 with some htm files and makefiles. For each of the Java clients a makefile 
 is provided: make.focus, make.nndb, make.sans, make.topsi, make.powder, 
 make.sics, makr.amor and make.watch. The purpose of each makefile can be deduced from 
 its name. Building the Java clients requires two steps each: 1) compiling and 
 2) building the jar file. The jar-file is a container file which contains
 all the classes necessary for running the application. This is the standard
 distribution format for the SICS Java clients. The necessary commands are 
 using the powder status display as example:
\begin{description}
\item[Compiling] make -f make.powder
\item[Jar-File] make -f make.powder jar  
\end{description}


\section{Kernel Objects and Modules}
This section describes the modules defining the SICS kernel.
\include{task}
\include{nserver}
\include{ini}
\include{passwd}
\include{network}
\include{nread}
\include{telnet}
\include{nconman}
\include{costa}
\include{interface}
\include{event}
\include{devexec}
\include{SCinter}
\include{macro}
\include{emonitor}
\include{perfmon}
\include{interrupt}
\include{ofac}
\include{servlog}
\subsection{The commandlog}
This is yet another logging facility of SICS. The idea is that all I/O
going to connections with user or manager level rights is logged.
This allows to figure out what really happened at an instrument. From
this base a scheme was introduced to automatically generate command
log files for each day. Additionally time stamps can be printed into
the commandlog at predefined intervalls.  In terms of an external
interface the commandlog just has a few functions for installing and
configuring the commandlog  from the interpreter plus a function for
writing to it. The rest is implemented as file statics in commandlog.c.  


\section{SICS Core Objects}
This section describes the SICS objects implementing commands and objects
common to all SICS instruments.
\include{scan}
\include{center}
\include{danu}
\include{drive}
\include{alias}
\include{buffer}
\include{ruli}
\include{o2t}
\include{selector}
\include{sicsexit}
\include{status}
\include{cron}
\include{optimise}
\include{token}
\include{udpquieck}
\include{xytable}

\section{SICS Hardware Objects}
This section deals with objects and modules representing instrument
hardware. Please be reminded that a hardware object within SICS
usually consists of two layers:
\begin{itemize}
\item The logical layer building the interface to SICS.
\item The driver layer actually interfacing to the hardware. 
\end{itemize}
This allows for the easy adaption to new hardware by exchanging
drivers.
The next thing to note is that most SICS hardware objects implement
at least one of the standard SICS interfaces:
\begin{itemize}
\item The drivable interface
\item The countable interface
\item The environment interface
\item The callback interface. 
\end{itemize} 
Please note, that there is some history in SICS hardware access. At
first there were no interfaces and objects implemented special
functions for themselves. These are still in the code. Some have their
right as utility functions. However, the preferred and supported way of
accessing SICS hardware objects is through the interface functions. 

\include{velo}
\include{velodorn}
\include{evcontroller}
\include{itc4}
\include{bruker}
\include{tclev}
\include{evdrivers}

\include{motor}
\include{pimotor}

\include{counter}
\include{histogram}
\include{sinqhmdriv}
\include{histsim}
\include{choco}
\include{serial}
\include{serialwait}
\include{sps}

\section{Powder Diffraction Specific Objects}
\include{dmc}
\include{nxdata}

\section{SANS specific Objects}
\include{mumo}
\subsection{NXSans}
The files nxsans.h and nxsans.c implement the NeXus writing functions for SANS. Also interpreter commands for configuring SANS data writing into SICS and for triggering data writing are implemented.  
\include{sanswave}

\section{FOCUS Specific Objects}
\include{faverage}
\include{fowrite}

\section{AMOR Specific Objects}
\include{amor2t}
\include{amorscan}
\include{amorstat}
\include{nxamor}

\section{Four-Circle Diffraction Specific Objects}
\include{hkl}
\include{hklscan}
\include{integrate}
\include{mesure}
\include{tricsnex}
\include{difrac}

\section{Helper Objects}
This section describes helper objects which implement useful data
structures or utilities.
\include{serialsinq}
\include{varlog}
\include{dynar}
\include{splitter}
\include{obpar}
\include{stringdict}
\include{fupa}
\include{nxsans}

\subsection{Further Helper Code}
Further helper code includes lld.*. This is a general linked list package.
It is documented in lld.h. All credits go to its original author. lld.c has
been modified slightly to resolve a memory problem.

napi.* is the NeXus API. This is documented in a separate document.

nxdict.* is the NeXus dictionary API, which is documented in another
separate document.

strdup.* is a fortified implementation of the standard utility strdup.

strrepl.c is the implmentation of a string replace.

uubuffer.* is a utility function which UUencodes a buffer. 

uusend.c is some helper code for sending UUencoded messages.

scaldate.* is an implementation of some julian date conversion
utilities. Is used in commandlog for incrementing date.

circular.* is the implementation of a circular buffer.   

\end{document}
