314 lines
11 KiB
TeX
314 lines
11 KiB
TeX
% 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}
|