PSI sics-cvs-psi_pre-ansto
This commit is contained in:
Douglas Clowes
313
doc/programmer/reference.tex
Normal file
313
doc/programmer/reference.tex
Normal file
@@ -0,0 +1,313 @@
|
||||
% 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}
|
||||
Reference in New Issue
Block a user