sics/doc/manager/managerman.tex

\documentclass[12pt,a4paper]{report}
%%\usepackage[dvips]{graphics}
%%\usepackage{epsf}
\setlength{\textheight}{24cm}
\setlength{\textwidth}{16cm}
\setlength{\headheight}{0cm}
\setlength{\headsep}{0cm}
\setlength{\topmargin}{0cm}
\setlength{\oddsidemargin}{0cm}
\setlength{\evensidemargin}{0cm}
\setlength{\hoffset}{0cm}
\setlength{\marginparwidth}{0cm}

\begin{document}
\begin{center}
\begin{huge}
SICS--Managers--Manual \\
\end{huge}
Version: \today\\
Dr. Mark K\"onnecke \\
Labor f\"ur Neutronenstreuung\\
Paul Scherrer Institut\\
CH--5232 Villigen--PSI\\
Switzerland\\
\end{center}
\clearpage
\clearpage
\tableofcontents
\clearpage

\chapter{Introduction}
This document describes the general setup of SICS, the configuration of the
 SICS server and its clients and the writing of macros in the
SICS macro language. This document is aimed at SICS system managers and
instrument scientists. This document requires that the SICS user
documentation
has been read and understood beforehand. For writing macros it is essential
to understand John Ousterhouts Tool Command Language,
which is described elsewhere.

% html: Beginning of file: `setup.htm'

\chapter{SICS programs, Scripts and Prerequisites}

\label{f0}

\section{Hardware}

The following hardware is usually present for any SICs instrument:
\begin{itemize}
\item An instrument computer
\item A Lantronix terminal server with 8-16 serial ports for connecting:
\item Motor controllers
\item Counter boxes
\item Temperature controllers.
\item Optionally 1-n histogram memory computers are present.
\end{itemize}
The terminal server software is provided by Lantronix, see the
appropriate manuals for the device for a description. The histogram
memories are 68000 VME or MEN-A12 onboard computers 
 running the VXworks realtime
operating system and some home grown histogramming software documented  
elsewhere. 

\section{Server programs}


For proper operation of an instrument the following software components are
required:
\begin{description}
\item[SerPortServer] This is a TCP/IP server which implements a special protocoll for
communicating  with serial ports. The actual communication with the
serial ports is done through the Lantronix terminal server. Both the
serial port protocoll and the SerPortServer are only documented in the
source code. The SerPortServer program is on its way out.
\item[TecsServer] This is a TCP/IP server which watches over temperature
controllers. The only known source of documentation about this
software is Markus Zolliker. 
\item[FileSync] This is a little UDP server which waits for UDP messages from the
instrument control program. Then the server starts a script which
synchronizes the local data directory with the central data storage on
the labarotory server. FileSync is configured through an
initialization file usually called fs.ini. See the comments in the 
 initialization file for more information. 
\item[SICServer] This is the actual instrument control server. The configuration of
this program is documented in this manual.  
\end{description}
Additionally a client program is needed which connects to the
instrument control server and provides a user interface to it.

\chapter{General SICS Setup}


SICS is a client server system. This implies that there is a server program
which implements all the functionlity and client programs which implement
the user interface. The client program is the only thing the user is
intended to see. This also means that the location of the client programs is
quite independent from the computer where the server runs.  In the following
the layout of a server installation is described as established at SINQ.  

For each instrument there is a data aquisition computer. On this computer
there exists a user name and consequently a home directory for the
instrument. In the following text this instrument root directory will be called
sicsroot. This root directory has the following subdirectories:
\begin{description}
\item[bin]  The directory where some executables live.
\item[inst\_sics] All instrument configuration files and the SICServer live in 
 this directory. Replace inst by the name of the instrument as appropriate.
\item[data] The data directory is the central place where all data files collected
at the instrument are stored. This directory contains subdirectories 
for each year. These directories hold the data collected at the
 instrument in this year plus a file named
DataNumber which keeps the current serial number of the data files. This
file should never be edited. At the start of each year the instruement manager
must create a new directory with an empty DataNumber
file. Additionally the
path variables both for the data file directory and the DataNumber
file have to be set to the new directory in the instrument
initialization file.  
\item[log]  The log directory contains the server log files and the automatically
generated client log files. Any now and then, and especially when disk space
problems loom, the client*.log files should be deleted by the instrument
manager.
\item[lib] Contains some files needed for running SICS clients locally.
\item[ doc]  This directory holds a copy of the SICS user documentation for the
instrument. These are html files which can be viewed with WWW-browsers such
as lynx or netscape.
\item[motor] This directory holds a script for reading and restoring the  motor
parameter from the EL734 motor controllers. And the motor parameters
stored in parameter files. It is the instrument scientists
responsability to save the motor parameters after changes to the
configuration of the instrument.
\item[tmp]  A directory for temporary and PID files.
\item[help] A directory for help files for the help system.
\end{description}
Besides these directories there should be nothing on the instrument account.
All evaluated data, personal command files etc. should be held on the normal
user account of the instrument user. 

\section{System Control}


All commands listed in this section have to issued with the privilege of the 
 instrument user account.

In order to watch over all these servers, the monit\footnote{See URL http://www.tildeslash.com/monit} software is used. This is
 a program which watches server processes and restarts them as necessary. 
 Monit can also be used to watch over hardware and the file system. Monit 
 writes a log file and can trigger e-mail alerts on certain 
 problematic conditions. 

Monit itself is controlled through a configuration file, .monitrc, which lives 
in the instrument accounts home directory.  Monit also uses another Tcl program  runwithpid which is responsible for starting and stopping server programs.
In order to configure all this, there is another program: makemonit which 
 creates the monit configuration file and copies and edits the runwithpid 
 program. The syntax of makemonit is: 
\begin{description}
\item[makemonit instrument terminalserver data-mount-point hm1 hm2 ..] instrument is the instrument name in lowercase, terminalserver is the 
 name of the terminal server used for serial port access, data-mount-point is 
 the name of file system onto which the instruments data is written. This is 
 followed by a list of all the histogram memory computers used by the 
 instrument.
\item[monitinit] monitinit is an alias which calls makemonit with all required parameters 
 for a given instrument in standard configuration.
\end{description}
 
Monit itself can be controlled with the following commands:
\begin{description}
\item[monit] Starts the monit daemon and all configured processes. This is only 
 necessary after a reboot of the system.
\item[monit status] This shows a status message listing the status of all configured servers 
 and the checked hardware.  The monit status is also available on the WWW from
 http://lns00.psi.ch/monit/instrument. Replace instrument with the appropriate
 instrument name.
\item[monit stop target] Stops the server process target. The following targest exist:
\begin{description}
\item[all] All processes
\item[sicsserver] The SICS server
\item[SerPortServer] The serial port server.
\item[sync] The file synchronisation server.
\item[tecs] The TecsServer for controlling environment devices.
\item[simserver] A simulation server(not on all instruments).
\end{description}
\item[monit start target] Starts a server process, targest are the same as described above.
\item[monit restart target] Stops and starts the process target. Targets are as listed above.
\item[monit quit] Stops monit alltogether. Please note, that servers stay running with
 this command. In order to sop everything the sequence: monit stop all; 
 monit quit is required.
\item[startsics]  This script starts all the necessary server programs for driving
the instrument through monit. 
\item[killsics] This script shuts down all instrument control servers properly through 
 monit.
\item[instsync] replace inst by the name of the instrument in lower case. This
script is invoked by the FileSync server and is responsible for
synchronizing the local data store with the one on the labaratory
server. This is usally done by calling the unix program rsync with
appropriate parameters.    
\end{description}
 
% html: End of file: `setup.htm'
% html: Beginning of file: `move.htm'

\section{Moving SICS}

\label{f2}
\subsection{ Moving the SICS Server to a new Computer}


This requires the following steps:
\begin{enumerate}
\item Create a new local account on the host computer. There is a
prefabricated account with the credentials: instbck/INSTBCKLNS on
lnsl15. 
\item Create the directory structure.
\item Create and edit a suitable DataNumber file for the instrument and put it
 into data/YYYY. YYYY is the year.
\item Edit the instrument configuration files and adapt the path names
to match the new configuration.
\item Try to start and debug.
\end{enumerate}

\subsection{Exchanging the Serial Port Server}


\begin{enumerate}\item Fetch a new  one and make sure that all cables are plugged as
they were in the old one. 
\item Create a new .monitrc file by running makemonit.
\item Exchange all references to the old terminal server in the instrument
 configuration files to the new terminal server.
\item Done!
\end{enumerate}

\subsection{Exchanging the Histogram Memory}


\begin{enumerate}\item Get a new histogram memory computer from either Gerd Theidel,
the test setup in the electronics barrack.
\item Put into the rack.
\item Configure the HM boot parameters through the console connected to
the serial port belonging to the HM. Instructions for this can be
found in the histogram memory documentation. Up to date boot 
 configuration parameters should be available under 
 /afs/psi.ch/group/sinqhm/boot/INST where INST is a place holder for the 
 instrument in upper case.
\item Adapt the instrument configuration file to reflect the new name of
the HM. 
\item Start and debug.
\end{enumerate}

% html: End of file: `move.htm'
% html: Beginning of file: `trouble.htm'

\section{SICS Trouble Shooting }

\label{f3} 
\subsection{Check Server Status}


One of the first things to do is to check the server status with: 
monit status.
 

\subsection{Inspecting Log Files}


Suppose something went wrong over the weekend or during the night and
you are not absolutely sure what the problem was. In such a case it is
helpful to look at the SICS log files. They live in the log directory
of the instrument account. For each day (or after each restart of the
SICS server) a new log file is created. They are named according to the
following convention:
\begin{verbatim} 
autoYYYY-mm-dd@hh-MM-ss.log
\end{verbatim}
 with YYYY denoting the year, mm the month, dd the day, hh the hour of
creation, MM the minute of creation and ss the seconds of
creation. The most recent log file can be looked at with the
{\bf sicstail} command. {\bf sicstail num} shows the last num lines
of the log file. Within SICS and especially in the SICS command line
client, the last 1000 lines of the log are accessible through the
{\bf commandlog tail num} command. The command log is also accessible
through the WWW at lns00. The log file is equipped with hourly time
stamps which allow to find out when exactly a problem began to
appear. 

There is also another log file, log/monit.log, which logs messages from 
 the monit daemon. This can be used to determine when server processes 
 were restarted or when hardware failed. 

Quite often the inspection of the log files will indicate problems
which are not software related such as:
\begin{itemize}
\item Communication problems (usually network)
\item Positioning problems of motors.
\item BAD\_EMERG\_STOP: the motor emergency stop was engaged. It must be
released before the motors move again. 
\item BAD\_STP: a motor had been switched off. 
\end{itemize}

\subsection{Restarting SICS}

 
\begin{description}\item[monit restart sicsserver] 
\end{description}
 
\subsection{Restart Everything}


If nothing seems to work any more, no connections can be obtained etc, then
the next guess is to restart everything. This is especially necessary if 
mechanics or electronics people were closer to the instrument then a
 nautical mile. 
\begin{itemize}
\item  Reboot the histogram memory. It has a tiny button labelled RST. That' s
the one. Can be operated with a hairpin, a ball point pen or the like.
\item Restart all of SICS with the sequence: monit stop  all; monit quit; monit
\item Wait for a couple of minutes for the system to come up. 
\end{itemize}
 
\subsection{Starting SICS Manually}


In order to find out if some hardware is broken or if the SICS server 
 initializes badly it is useful to look at the SICS servers startup messages. 
The following steps are required:
\begin{itemize}
\item monit stop sicsserver
\item cd \~{}/inst\_sics
\item ./SICServer inst.tcl \mbox{$|$} more
\end{itemize}
Replace inst by the name of the instrument, as usual. Look at the screen 
 output in  
 order to find out why SICS does not initialize things or where the 
 initialization hangs. Do not forget to kill the SICServer thus started when 
 you are done and to issue the command: {\bf monit start sicsserver} in order 
 to place the SICS server back under monits control again.  
 

\subsection{Test the SerPortServer Program}


Sometimes the SerPortServer program hangs and inhibits the communication with 
 the RS-232 hardware. This can be diagnosed by the following procedure: Find 
 out at which port either a EL734 motor controller or a E737 counter box
 lives. Then type:{\bf asyncom localhost 4000 portnumber} This yields a
 new prompt at which you type {\bf ID}. If all is well a string identifying 
 the device will be printed. If not a large stack dump will come up. 
 The asyncom  program can be exited by typing {\bf quit}. If there is 
 a problem with the
 SerPortServer program type: {\bf monit restart SerPortServer} in order to 
 restart it.  
 

\subsection{Trouble with Environment Devices}


The first stop for trouble with temperature or other environment devices 
 is Markus Zolliker. A common problem is that old environment controllers 
 have not be deconfigured from the system and still reserve terminal server 
  ports. Thus take care to deconfigure your old devices when swapping.  
 

\subsection{ HELP debugging!!!!}


The SICS server hanging or crashing should not happen. In order to sort such
problems out it is very helpful if any available debugging information is
saved and presented to the programmers. Information available are the log
files as written continously by the SICS server and posssible core files
lying around. They have just this name: core. In order to save them create a
new directory (for example dump2077) and copy the stuff in there. This looks
like:
\begin{verbatim} 
/home/DMC> mkdir dump2077
/home/DMC> cp log/*.log dump2077
/home/DMC> cp core dump2077
\end{verbatim}
The {\tt /home/DMC> } is just the command prompt. Please note, that core
files are only available after crashes of the server. These few commands
will help  to analyse the cause of the problem and to eventually resolve it.
% html: End of file: `trouble.htm'

\chapter{The SICS Initialization File}
% html: Beginning of file: `ini.htm'

\section{Overview of SICS Initialization}

\label{f4}
 The command to start the SICServer is: {\bf  SICServer inifile }. So, what
happens at the initialization of the SICS server? First, internally, a set
of standard SICS commands is initialized, than a set of special
initialization commands. These are special commands which help to configure
the SICS server to match the actual hardware present on the hall floor and
to define the commands available later on.  Following this, the SICS server
will read the initialization file specified on the command line or servo.tcl
as a default. Using the data supplied in this file, the server will be
configured. At this stage all special initialization commands, all
Tcl-mechanisms and all SICS commands already initialized are available.
After this is done, the server will delete the initialisation commands from
its internal command list (No need to carry them around all the time). Now a
status backup file will be read. This file contains normal SICS statements 
which initialise parameter values to the values  they had before the last
shutdown of the server. Such a file is automatically written whenever a 
normal shutdown of the server happens or variables change. 
 
The SICS server configuration file is essentially a SICS macro language
file. This implies that all general SICS commands and Tcl mechanisms are 
available. Additionally the configuration file (and only the configuration
file) may use special commands for the installation of:
\begin{itemize}
\item SICS server options.
\item SICS variables.
\item Special commands.
\item Hardware 
\end{itemize}

Actually the SICS servers configuration is rarely stored in one file
but in several files which are included by the main configuration
file. In general the following files are present:
\begin{description}
\item[inst.tcl] Replace inst with the name of the instrument in lowercase. This is
the main initialization file. It should contain all the hardware
initialization. 
\item[instcom.tcl] Again replace inst with name of the instrument in
lowercase. This file holds instrument specific commands defined in the
Tcl macro language. This file is automatically included by inst.tcl. 
\item[scancommand.tcl, tecs.tcl, log.tcl] Some macro definitions are used by so many instruments that
it was deemed appropriate to hold them in separate files. Such files
are included from instcom.tcl. 
\end{description}

% html: End of file: `ini.htm'
% html: Beginning of file: `option.htm'

\section{SICS Options and Users}

\label{f5}
 The SICS server has an internal options database which holds such  values
 as port number to listen too and the like. Additionally there exists a user
 database. Currently these values  are configured from the initialisation
 file. The commands to do this are:
\begin{itemize}
\item  {\bf  ServerOption name value } defines the server option name  to be
value.
\item  {\bf  SicsUser name password accesscode } defines a user with name
and password and an access right accesscode. Accesscode is an integer from 1
to 3 for User, Manager and Spy rights. A user with Spy right may look at
everything but cannot change anything. A user with user privilege may change 
most of the SICS parameters, perform measurements etc. A user with manager 
privilege may do everything to the system.
\end{itemize}
 The Sics server currently uses the following options:
\begin{itemize}
\item  {\bf  ReadTimeOut } The server checks in each cycle of the main loop
fro pending commands. Het waits for new commands for a specific period of 
time. This value is the ReadTimeOut. It should be as short as possible. This
value may need to be increased if there are network performance problems. A
good value is 100.
\item  {\bf  ReadUserPasswdTimeout } This is the time a client has to  send a
username password pair after a connection request. If nothing comes in in
that time, the connection request is terminated.
\item  {\bf LogFileBaseName } defines the path and the base name for  the
server log file.
\item  {\bf  ServerPort } defines the port number the server is listening
to. Should be greater than 1024 and less than 64000. The port number should
also be different from any other server port number in use on the system.
Otherwise evil things may happen. 
\item  {\bf  InterruptPort } The SICS server can handle interrupts coming in
as UDP messages on a special port. This option defines this UDP port
number. The choice of possible port numbers is limited by the constraints 
given above in the ServerPort section. Espacillay this port number MUST be
different from the ServerPort number. The UDP messages accepted are expected to consist of the string
SICSINT followed by an interrupt number. For interrupt numbers see file
interrupt.h.
\item  {\bf  DefaultTclDirectory } specifies where Tcl defined commands  are
stored. When this is properly defined Tcl will autoload commands.
\item  {\bf  statusfile } defines the file to which he current state  will be
saved on close down of the server and restored from at startup time. 
\item {\bf TelnetPort} The port number where the SICS server will be
listening for telnet connections. If this option is missing login via telnet
to the SICS server is disabled.
\item {\bf TelWord} In order to login to SICS via telnet a magic word is
needed. The login word, This option defines this word. If this option is
missing telnet login to SICS is disabled.
\item {\bf LogFileDir} This server option defines the directory where
commandlog log files are kept.
\item {\bf RedirectFile} This defines a filename to which all output to
stdout and stderr is logged by the SICS server. This  is mainly a
debugging feature. 
\item {\bf TecsPort} The port number at which the Tecs temperature
control server is listening. 
\end{itemize}
  
% html: End of file: `option.htm'
% html: Beginning of file: `var.htm'

\section{SICS Variables }

\label{f6}
In SICS most parameters necessary for instrument control are kept with the SICS
object implementing the functionality. However, there are some odd bits of
information which need to be known, mostly additional information about and
from the user, which should go into data files. Such information  is kept in 
SICS variables, created with the command VarMake detailed below.

Variables are also used in order to control the SINQ automatic file name
creation scheme for data files. At SINQ, data files are put into a special
directory. The actual name consists of a prefix, a sequential number, the
last two digits of the year and an ending. All these components are
controlled by variables.

The exact syntax for creating variables looks like this:
\begin{itemize}
\item  {\bf  VarMake name type access } creates a simple variable name.  The
variable type can be Text, Int or Float. The access parameter defines who
may may change the variable. Possible values are: Internal, Manager, User
and Spy.
\end{itemize}

There are quite a few SICS variables which have special usages and should be
present. Some of them may need to be set by the user, all of them should be
inspectable by the user. Many of these variables are used when writing
NeXus data files. These special variables are:
\begin{description}
\item[ sample]  The sample name. To be set by the user.
\item[ title.]  The experiment title.
\item[ User]  The name of the user to be specified in a data file.
\item[ Instrument.]  The name of the instrument.
\item[ SicsDataPath] The full path name of the instruments data directory. Should have a / at
the end.
\item[ SicsDataPrefix]  The prefix to use for data file names.
\item[ SicsDataPostFix]  The ending to use for the data file name. Including the '.'.
\item[ Adress]  The users adress.
\item[ phone]  The users phone number.
\item[ email]  The users e-mail adress.
\item[ fax]  The users fax number.
\end{description}
 
Some of the variables stated above should never be changed by a user. This
can be achieved by the variable lock command described in the user
documentation.
% html: End of file: `var.htm'
% html: Beginning of file: `hwini.htm'

\section{SICS Hardware Configuration}

\label{f7}
Hardware is configured into the SICS system by executing special hardware
configuration commands from the server initialisation file. These commands
are described here. Much SICS hardware is hooked up to the system via RS-232
interfaces. The SICS server communicates with such devices through a serial
port server program running on the instrument computer.
 All such devices require on 
initialisation the following parameters:
\begin{itemize}
\item {\bf hostname} The name of the instrument computer.
\item {\bf port} The port number where the serial port server program is
listening for requests. It is usually 4000.
\item {\bf channel} The number of the RS-232 interface port 
 on the terminal server. 
\end{itemize}

\subsection{Bus Access}


SICS and its internals cover many common usage cases. However there are always 
 situations where SICS has to be bypassed and commands to be sent to  a
 controller directly. This can happen in order to satisfy a special request or 
 as first step in the integration of a special piece of hardware into SICS. In 
 order to do such things the following facilities are available:

\subsubsection{Direct Access to RS232 Controllers or TCP/IP Controllers.}


Both controllers listening on a TCP/IP port or RS-232 devices connected to a
 terminal server can be directly accessed through the RS232 commands.  The 
 first step in using this system is always to accounce the controller to SICS
 using the command:
\begin{verbatim} 
MakeRS232Controller name terminalserver port
\end{verbatim}
in the SICS initialization file. 
For example:
\begin{verbatim} 
MakeRS232Controller hugo psts213 3004
\end{verbatim}
name is the SICS name for the controller, terminalserver is the name
of the terminal server the device is connected to and port is the port
number at which the terminal server publishes the RS232 channel to
which the device is connected. This is usally the port number plus 3000.

Now various commands are available for interfacing with the RS232
controller. In the following description the SICS name of the
controller is replaced by the symbol rs232name.
\begin{description}
\item[rs232name sendterminator] prints the current terminator used when sending data to the device
as hexadecimal numbers.  
\item[rs232name sendterminator h1h2..hn] sets the current terminator used when sending data to the device
to the characters described by the hexadecimal numbers h1 to hn. The
numbers are in the format 0xval, where val is the hex number. 
\item[rs232name replyterminator] prints the current terminator expected to terminate a response
from the device as a hexadecimal number.
\item[rs232name replyterminator h1h2..hn] sets the current terminator expected to terminate a response from
the device  to the characters described by the hexadecimal numbers h1
to hn. 
The numbers are in the format 0xval, where val is the hex number. 
\item[rs232name timeout] prints the current timeout when waiting for a reponse from the
device.
\item[rs232name timeout val] sets the timeout for waiting for responses from the device. The
value is in microseconds. 
\item[rs232name send data data data] sends the remainder of the line to the RS232 device and waits for
a response terminated with the proper reply terminator specified. This
commands waits at maximum timeout microseconds for a response. If a
valid response is obtained it is printed, otherwise an error message
occurs.
\item[rs232name write data data data] writes the remainder of the line after write to the device without
waiting for a response.
\item[rs232 available] checks if data is pending to be read from the device. 
\item[rs232 read] reads data from the device.   
\end{description}

\subsubsection{Accessing Serial Ports (Old System)}


In addition to the system describe above there is another system for accessing 
 serial ports which uses the SerPortServer program. The use of the system is 
 deprecated, new software should use the commands describe above. Nevertheless
 the older sytem is described here for reference.
  
Serial port access is implemented as an extension to the Tcl macro language.
Essentially this is the same implementation as used in the program psish.
 This section describes how to use  serial port access. Several 
 steps have to be performed:
\begin{enumerate}
\item Install the serialport command into the SICS server. This requires two lines to be added to
the server startup script:
\begin{itemize}
\item SerialInit
\item TclPublish serialport UserRights
\end{itemize}
Where UserRights stands for one of the possible SICS user rights. 
 See documentation
for TclPublish above.
\item  Each separate serial port will be represented by a name in the SICS server
after it has been initialized. This name is also a command. These port names 
 live  in the Tcl interpreter and must be made accessible with TclPublish. 
 For example for 
a port named p1 include this line in the server startup script:
\begin{itemize}
\item TclPublish p1 User
\end{itemize}
 Replace User with the correct access code you want for a serial port. It is 
 recommended
to restrict serial port access to SICS managers only. 
\item  After starting the SICS server the command serialport is now available. 
\item  Now a serial port can be initialized with a command like this:
\begin{itemize}
\item serialport name1 SerPortServer.host port channel force
\item Example: serialport p1 localhost 4000 5
\end{itemize}
Such a command creates the command name1 and links it with serial port channel
channel on the instrument computer (localhost) running the SerPortServer program . Port is the port number on which the 
 SerPortServer is listening for connections (usually 4000).
The last flag force is optional. If something is there, the connection to that
port is done on a separate socket of its own. This has to do with some 
feature of the software interface to the SerPortServer serial port server. 
This 
software interface tries to direct messages for multiple channels through one
socket connection between the host and the Macintosh server. This is perfectly
fine as long as none of the commands through this socket takes a long time
to execute. However, if a RS-232 device takes a long time to respond, the whole
socket is blocked. Fortunately, the  serial port server runs a separate 
thread of execution for each different socket. By forcing a new socket it can
be achieved that such  a slow device is decoupled from the rest. Exactly this
is achieved with the force flag.
\item  Once the port has been initialised (for example p1) it is ready to 
 operate.
The port object allows to send data to the serial port and receive data from
it. Furthermore some configuration is possible. The syntax is like this:
\begin{description}
\item[portname -tmo number] Sets the timeout for the serial port. This is the maximum amount of time 
the serial port server waits for data to arrive from the RS-232 device.
Increase this if a lot of {\tt \_BAD\_TMO} error messages creep up.
\item[portname -sendterm string]  Sets the terminator which will be automatically added to the string 
 which is 
sent. Some RS-232 devices require special terminators in order to accept a command.
The serial port implementation ensures that such a terminator is sent after
each message. This command allows to configure this terminator. Please note, 
that the terminator string needs to be enclosed in quotes. An example:
\begin{itemize}
\item {\tt p1 -sendterm {\tt{}"{}}\mbox{$\backslash$}r\mbox{$\backslash$}n{\tt{}"{}}}
\end{itemize}
This sets the terminator to carriage return - line feed.
\item[portname -replyterm string.] The serial port  server expects the RS-232 device to send a terminator
when it is done with sending answers. It even supports multiple lines to be
sent as a reply. This expected reply terminator is set with this command. 
The string may may be four characters long. An example: {\tt 1\mbox{$\backslash$}r\mbox{$\backslash$}n} sets
the expected terminator to one of {\tt \mbox{$\backslash$}r\mbox{$\backslash$}n}. One of them is expected. 
Thus the  first character is the count of terminators to expect, followed by 
 the characters possible as terminators. This string must usually be quoted.  
\item[portname blablalakjdl] When none of the options -tmo, -replyterm, -sendterm, is found everything 
 after portname is sent to the RS-232 device. The reply from the RS-232 
 device is printed.
\end{description}
  \end{enumerate}
The defaults set for the configuration parameters of the serial port connection
are suited for the EL734, EL737 and ITC4 devices usually encountered at SINQ. 
 For other RS-232 devices consult the manuals hopefully delivered with the 
 device.
The defaults are: 100 for timeout, {\tt 1\mbox{$\backslash$}r\mbox{$\backslash$}n} for the reply terminator and
{\tt \mbox{$\backslash$}r\mbox{$\backslash$}n}for the send terminator.

\subsubsection{GPIB Controller Access}


GPIB is yet another bus system. Up to 30 devices can share the bus and
transfer data on it. SICS likest to speak to GPIB devices through the
National Instrument ENET-100 TCP/IP bridge. In order for this to work
the National Instruments driver software must have been installed on
the computer running SICS. SICS has to be compiled with the define
HAVENI defined and the proper paths to the header file and library
configured. Then an GPIB controller can be installed into SICS with the
command:
\begin{verbatim} 
MakeGPIB name drivertype
\end{verbatim}
Name is the name under which the GPIB controller is addressable within
SICS afterwards. drivertype is the driver to use for the GPIB
device. Supported values are:
\begin{description}
\item[sim] Simulation
\item[ni] National instruments driver, see above.
\end{description}
The GPIB controller supports a couple of commands for communicating
with devices on the GPIB bus directly. Use with extra care because it
is very easy to lock things up on the GPIB bus. In the following
documentation of the command set it is assumed that a GPIB controller
has been configured into the system under the name {\bf gpib}. Please
note, that managers privilege is required in order to be allowed to
wrestle  with this controller.
\begin{description} 
\item[gpib attach controller-no gpib-address gpib-secondary timeout  eos eot] This attaches the GPIB controller to a certain device at a certain
 address for later communication. The return value is an integer
 handle which will be used later on a s a handle devID when referring
 to the connection. The parameters are:
\begin{description}
\item[controller-no] The number of the GPIB controller on the computer. There may be
more then one GPIB controllerinstalled on a given system. Usually this
is 0.
\item[gpib-address] The GPIB address of the device on the bus.
\item[gpib-secondary] GPIB devices may have a seconadry address. This can be specified
with this parameter. Usually this is 0.
\item[timeout] The time to wait for answers on the GPIB bus. 13 is 10 seconds and
ussually a good value. 
\item[eot] A parameter determining the termination mode on this
connection. Consult NI documentation for this or leave at 0.
\item[eoi]  A terminator. Set to 1 or understand NI documentation for this
parameter. 
\end{description}
\item[gpib detach devID] Breaks the connection described through devID. devID is the return
value from attach.
\item[gpib clear devID] Tries to clear the GPIB buffers for the conenction described
through devID. Usually in vain.
\item[gpib   send devID bal bla bla] sends data to the device at devID.
\item[gpib sendwithterm devID string terminator] Sends string to the device at devID. The terminator character
identified through the integer terminator is automatically
appended. Use this to send things which require a
terminator. Terminators included in strings sent by send get messed up
through Tcl!
\item[gpib read devID] Reads data from the device at devID and returns it as a string.
\item[gpib readtillterm devID terminator] Read from teh device devID unti the terminator character described
through the interger terminator is read. Then return the data read as
a string. 
\end{description}

\subsection{Controllers}


For the same reason as stated above, it is necessary to represent controllers
 within SICS. Controllers implement more then only device access but also 
 maintain common state or implement special behaviour.

\subsubsection{ECB Controllers}


ECB controllers are at the heart of the Risoe data aquisition
system. These are essentially Z80 processors wired to the GPIB
bus. Functions can be invoked in this processor by sending a function
code followed by the contents of 4 8 bit registers. As a result the
contents of the registers after the function call are returned. A ECB
can be made knwon to SICS through the initialisation command:
\begin{verbatim} 
MakeECB name gpib-controller gbib-controller-number gpib-address
\end{verbatim}
The parameters:
\begin{description}
\item[name] The name used as a token for this controller later on.
\item[gpib-controller] the name of the GPIB interface to use. See above.
\item[gbib-controller-no] The number of the GPIB board in the system
\item[gpib-address] The GPIB address of the ECB on the GPIB bus.
\end{description}
Once installed, the ECB controller understands a few commands:
\begin{description}
\item[ecb1 func funcode d e bc] Invoke ECB function funcode with the registers d e b c.Returns the
contents of the registers d e b c. Function codes and register
contents are documented, if at all, in the ECB documentation. In fact, as
 ECB documentation is not available, the only documentation on ECB is the 
 source code of tascom. 
\item[ecb1 clear] Tries, usually in vain, to clear the communications interface to
the ECB. 
\item[ecb1 toint char] A helper function which converts the character char to an
integer. Tcl does not seem to be able to do that. 
\end{description}

\subsubsection{Siematic SPS Controllers}


Siematic SPS controllers are used at SinQ for handling all the things which
fit nowhere else. Such as operating air cushions on some instruments,
reading variables from ADC's, reading status of shutters or other parts of
the instrument and the like. Those SPS units have an RS-232 connector and
understand a simple ASCII command protocoll.
 The Siematic SPS and its command protocoll are
special to PSI and this section is probably of no interest to SICS managers
 outside. The SPS basiaclly support three operations:
\begin{itemize}
\item Push a button (Set a Digital I/O Bit).
\item Read a status of instrument status packed into a bit (Read Digital I/O) .
\item Read an ADC.
\end{itemize}
  This is so user unfriendly that the usage of the SPS will mostly be packaged 
into Tcl-macros. 

A SPS unit can be configured into the SICS server with the command:\newline
{\bf MakeSPS name macintosh port channel} \newline
The parameters are: the name of the SPS in SICS, the serial port server
computer, the port where the serial port server is listening and the
channel number of the SPS unit at the serial port server computer. An
example: \newline
MakeSPS sps1 lnsp25.psi.ch 4000 6 \newline
configures a SPS unit at lnsp25.psi.ch at channel 5. The serial port server
is listening at port number 4000. The SPS unit will be accessible as sps1 in
SICS.

After configuartion the following four commands are understood by name,
shown with sps1 as example:
\begin{description}
\item[sps1 push byte bit] Corresponds to pushing the button mapped to the bit bit in the byte
byte. 
\item[sps1 adc num]  Reads the value in the ADC num. num can be between 0 to 7 for a maximum
of eight ADC's. Please note, that the values read are raw values which
usually must be converted in some way to physically meaningful values.
\item[sps1 status bit] Reads the status of the bit bit. bit can be in the range 0 - 128.
\item[sps1 stat2 byte bit] Reads the status bit bit in status byte byte. Is equivalent to status,
but adds some syntatctic sugar.
\end{description}
For all conversion factors, for all mappings of bytes and bits, consult the 
electronician who coded the SPS.

\subsubsection{General Controller Object and Choppers}


Chopper systems are handled via a generic controller object. This basicly 
consists of two components: One object represents the actual
controller. This basic object allows to query parameters only. Then
there is for each parameter which can be controlled from SICS in this
controller an adapter object. These adapter object are virtual motors
which can be driven with the normal run or drive commands. Currently
two drivers for this scheme exists: one for a simulated device,  the
other for the Dornier Chopper Controller at FOCUS. The first step when
initializing this system is the installation of the general controller
object into SICS. This is done with the commands:  
\begin{verbatim} 
MakeChopper name sim
MakeChopper name docho mac port channel
\end{verbatim}
The first command simply installs a simulated controller. 
The second command install a controller with a driver for the FOCUS
Dornier Chopper system. Mac, port and channel are the usual Macintosh
terminal server parameters which describe where the chopper controller
is connected to through its RS-232 interface. After both commands the
controller is available as command name within SICS.

A drivable parameter at this controller is installed with a command
similar to this:
\begin{verbatim} 
ChopperAdapter vname cname pname lower upper
\end{verbatim}
vname is the name under which the virtual motor will appear in
SICS. cname is the name of the controller object installed into SICS
with the commands in the previous paragraph. pname is the name of the
drivable parameter in the controller. upper and lower are the upper
and lower limits for this parameter. More then one of these commands
can be given for each general controller. 

After this, the parameter can be modified by a command like:
\begin{verbatim} 
drive vname newvalue
\end{verbatim}

\subsection{ Motors}


The following commands are available to install motors into the system:
\begin{description}
\item[ Motor name SIM lowlim uplim err speed]  This command creates a simulated
motor with the lower limits lowlim, the upper limit uplim, an ratio of
randomly generated errors err and a driving speed of speed. Use this for
testing and instrument simulation. If err is less then 0, the motor will
not create failures and thus can be used in a instrument simulation server.
\item[Motor name EL734 host port chan no ] This command creates a stepper motor named name which is controlled through a
El734 motor controller. The
parameters host, port, chan have the meanings defined above. no is the
number of the motor in the EL734 motor controller. 
\item[Motor name EL734DC host port chan no ] This command creates an analog motor named name which is controlled 
 through a El734DC motor controller. The
parameters host, port, chan have the meanings defined above. no is the
number of the motor in the EL734DC motor controller. 
\item[Motor name el734hp rs232controllername motornum] Creates a motor object name using the newer motor drivers which access 
 the motor controller directly, without the serial port server. 
 rs232controllername is the name of a connection to the motor controll which 
has been set up with MakeRS232, above. Motornum is the number of the motor in 
 the controller. 
\item[MakePIMotor name c804 pararray] Creates a motor name connected to a C804 motor controller from the
 manufacturer Physik Instrumente. Pararray is a Tcl array holding the 
 initialization information. The follwoing elements are required in this
 array:
 \begin{description}  \item[Computer, port, channel   ] The standard connection parameters.
  \item[upperlimit, lowerlimit  ] The limits for this motor.
  \item[motor  ] The number of the motor in the motor controller. 
 \end{description}
 \item[Motor name pipiezo  pararray] Creates a piezo electric positioning device. Again the controller is a
 Physik Instrumente controller. pararray has the same meaning as for the 
 C804 controller given above. 
\item[Motor name ecb ecbcontroller ecb-number lowerlimit upperlimit] This creates a motor which is controlled through the Risoe ECB
  electronic. The parameters:
\begin{description}
\item[ecbcontroller] The ECB controller to which this motor is connected to. See below
for more on ECB controllers.
\item[ecb-number] Number of the motor in the ECB system.
\item[lowerlimit] The lower hardware limit for this motors operation
\item[upperlimit] The upper hardware limit for this motors operation
\end{description}
In contrast to normal motors, the ECB motors have quite a number of
hardware parameters which must be configured. The general syntax to
configure them is: motorname parametername value. The following
parameters are available:
\begin{description}
\item[encoder] 0 if there is no encoder for this motor, 1-3 for the encoder used
for this motor.
\item[control] The control bit flag. This falg determines if the motor sets a
control bit in the ECB controller. This control bit can be used to
drive air cushions and the like. If required set to 1, else leave at
0.
\item[delay] Delay time to wait after setting a control bit.
\item[range] The speed range for the motor: 0 for slow, 1 for fast
\item[multi] The ECB controller supports up to 24 motors. In some instances
this is not enough. Then one ECB channel can be multiplexed into
several motors. This flag (),1) determines if this is the case.
\item[multchan] The multiplexer channel for a multiplexed motor.
\item[port] The ECB port a multiplexed motor is using.
\item[acceleration] The speed with which the motor accelerates to its final speed.
\item[rotation\_dir] Rotation direction of the motor.
\item[startspeed] Starting speed of the motor.
\item[maxspeed] The maximum speed for this motor.
\item[auto] Speed in automatic mode
\item[manuell] Speed used when driving the motor through the manual control box.
\item[offset] When using an encoder: the offset between the motor zero and the
encoder zero.
\item[dtolerance] hardware tolerance of the motor.
\item[step2dig] conversion factor from encoder steps to physical values.
\item[step2deg] Conversion factor from motor pseudo encoder steps to physical
values.
\item[backlash] In order to correct for backlash, Risoe motors always approach a
target position from the same direction. In order to do this the motor
has to overshoot and drive back when driving in the wrong
direction. The parameter backlash determines how much to overshoot. 
\end{description}
 ECB motors have another quirck: 8 motors in a rack share a power
supply! This has the consequence that only one of the 8 motors can run
at any given time. In SICS this is directed through the anticollider
module described elsewhere.
\end{description}

\subsection{Counting Devices}


\begin{description}\item[MakeCounter name SIM failrate] This command creates a simulated single counter
accessible as object name. Failrate is the  per centage of invocations
at which the counter will generate a random failure for testing error
treatment code. If failrate is less then 0, there are no
failures. This can be used in a instrument simulation server. 
\item[MakeCounter name mcstas] Creates a counter which interoperates with a 
 McStas (cf.\ Section~\ref{f8}) simulation. Please note,
 that the McStas module mccontrol must have been initialized before this initialization 
 can work. 
\item[MakeCounter name EL737 host port chan ] This command creates a single
counter name, using an EL737 driver. The counter is at host host, listening
at port port and sits at serial port chan.
\item[MakeCounter name EL737hp terminalserver port] Creates a counter object name which uses the faster driver which connects 
 directly to the terminal server without the serial port server program. 
 Terminalserver is the name of the instruments terminal server. Port is the
 port number at which the terminal server publishes the port at which the EL737
 controller is connected. Usually this 3000 + port number.
\item[ MakeCounter name ecb ecb-controller] Installs a counetr on top of the Risoe ECB hardware. The only
parameter is the name of the ECB controller to use. 
\item[MakeHMControl name counter hm1 hm2 hm3] At some instruments (for instance TRICS) multiple counters or
histogram memories are controlled by a master counter which watches
over presets and the like. This command installs a virtual counter
which does exactly that. The parameters are:
\begin{description}
\item[name] The name of the virtual counter in SICS
\item[counter The name of the master counter] 
\item[hm1, hm2, hm3] Up to three slave counting devices. 
\end{description}
\end{description}

\subsubsection{Histogram Memory}


Due to the large amount of parameters, histogram memories are configured
differently. A histogram memory object is created using a special 
creation command. This command is described below. Then  a lot of options need to
be configured. The commands used for setting these options and their meanings 
are defined in the  user  documentation because histogram memories
may be reconfigured at runtime. The sequence of configuartion options is
ended with the command hmname init. This last command actually initialises the
HM. Histogram memory objects can be created using the command:
\begin{description}
\item[ MakeHM name type]  The parameter name specifies the name under which the HM will be
avialable in the system. type specifies which type of driver to use.
Currently these drivers are supported: 
\begin{description}
\item[SIM ] for a simulated HM
\item[SINQHM ] for the SINQ histogram memory 
\item[tdc ] for the Risoe histogram memory.
\item[mcstas ] for the integration with the  McStas (cf.\ Section~\ref{f8}) simulation.
\end{description}
\end{description}
 Please care to note, that the SINQHM
requires a counter box for count control. This counter must have been
defined before creating the HM object.
As an example the configuration of a SINQHM HM with the name banana will be
shown:
\begin{verbatim} 
MakeHM banana SINQHM         
banana configure HistMode Normal
banana configure OverFlowMode    Ceil
banana configure Rank     1
banana configure dim0   400
banana configure BinWidth 4
banana preset 100.
banana CountMode Timer
banana configure HMComputer psds04.psi.ch
banana configure HMPort 2400
banana configure Counter counter
banana init
\end{verbatim}

\subsection{Velocity Selectors}


A velocity selector is configured in a three  step process. First a Tcl array
is filled with the necessary configuration options for the actual velocity
selector driver. In a second step the
velocity selector is created with a special command. In a third step the
forbidden regions for the velocity selector are defined. Currently two
drivers for velocity selctors are known: a SIM driver for a simulated
velocity selector and a DORNIER driver for a Dornier velocity selector
hooked to a SINQ serial port setup. The last one needs a parameter array
containing the fields Host, Port, Channel and Timeout. Host, Port and
Channel have the meanings as defined at the very top of this section.
Timeout is the maximum time to wait for responses from the velocity selector.
A large value is required as the dornier velocity selector is very slow.
The second step is performed through the following commands:
\begin{description}
\item[VelocitySelector name tilt-motor SIM]  This command installs a simulated velocity selector with the name name
into the system. tilt-motor is used for driving the tilt angle of the
selector. tilt-motor must exist before this command can be executed
successfully.
\item[VelocitySelector name tilt-motor DORNIER arrayname]  This command installs a dornier velocity selector into the system. name
and tilt-motor have the same meanings as described above. arrayname is the
Tcl-array with the driver configuration parameters. 
\end{description}
 As an example the configuration of a dornier velocity selector named 
nvs is shown:
\begin{verbatim} 
set dornen(Host) lnsp25.psi.ch
set dornen(Port) 4000
set dornen(Channel) 6
set dornen(Timeout) 5000
VelocitySelector nvs tilt DORNIER dornen
nvs add -20 28800
nvs add 3800 4500
nvs add 5900 6700
nvs add 8100 9600
\end{verbatim}

% html: End of file: `hwini.htm'
% html: Beginning of file: `gencom.htm'

\section{Initialization of General Commands}

\label{f10}
This section gives details on the initialization of commands which are
 common to many different instruments. The command set of SICS can be tailored
 to cover many specific needs.  Moreover this system allows to replace 
 functionality by other implementations suited to another users taste. This
 is a list of common command initialization commands. 
\begin{description}
\item[MakeRuenBuffer ] MakeRuenBuffer makes the R\"unBuffer system available.
\item[MakeBatchManager \mbox{$[$}name\mbox{$]$}] Installs the new batch buffer management system. If no name is
given, the default will be exe. 
\item[MakeDrive] MakeDrive creates the drive and run command.
\item[ Publish name access]  The SICS server uses Tcl as its internal macro language. However, it 
was felt that the whole Tcl command set should not be available to all users
from the command line without any protection. There are reasons for this: 
 careless use of Tcl may clog up memory, thereby grinding the system to a 
 halt. Invalid Tcl statements may cause the server to hang. Last not least, 
 Tcl contains commands to manipulate files  and access the operating system. 
 This is a potential security problem when the server is hacked. However, 
 in order to make macro procedures available the Publish
 command exists. It makes a Tcl command name available to SICS users with the 
 access code access.  Valid values for access are: Internal, Mugger, User 
 and Spy.
\item[TokenInit tokenpassword]  This command initialises the token control management system with the
token command. The single parameter tokenpassword specifies the password for
the token force command.
\item[MakeOptimise name countername] This command installs the Peak Optimiser into the SICS server. The Peak
Optimiser is an object which can locate the maximum of a peak with respect
to several variables. The arguments are: name, the name under which the Peak
Optimiser can be accessed within SICS and countername, which is the name of
an already configured SICS counter box. 
\item[MakeO2T nam OM 2TM] creates an omega 2Theta virtual motor 
with name nam for omega 2Theta scans. OM defines an omega motor, 2TM a two
theta motor.
\item[MakeDataNumber SicsDataNumber filename] This command makes a
variable SicsDataNumber available which holds the current sequential data
 file number. filename is the complete path to the file were this data
number is stored. This file should never, ever be edited without good
reason, i.e. resetting the sequential number to 0 at the beginning of a
year. 
\item[MakeXYTable myname] Creates a XYTable object with the name myname. This object can store a 
 list of x-y values.  
\item[MakeSinq] Install the listener module for the accelerator divisions broadcast 
 messages. This creates a command sinq. 
\item[MakeMaximize counter] Installs a command max into SICS which implements a more efficient 
 algorithm for locating the maximum of a peak then scanning and peak or
 center. 
\item[MakeMaxDetector name] Installs name into SICS which implements a command for locating 
 maxima on a two dimensional histogram memory image.
\item[MakeLin2Ang name motor] Creates a virtual motor name which translates an input angle into a  
 translation  along a tangent to the rotation axis. The distance of the 
 translation table can be configured as variable: name length once this
 is established. 
\item[MakeSWHPMotor realmotor switchscript mot1 mot2 mot3] Creates  switched motors mot1, mot2 and mot3 for real motor
 realmotor. For switching the script switchscript is used. This 
 can be used when several motors are operated through the same 
 motor driver. This implementation is not completely general now.   
\end{description}

\subsection{Monochromators}


A monochromator is represented in SICS through a monochromator object which
 holds all the parameters associated with the monochromator and virtual 
 motors which drive wavelength or energy. The commands to configure such a 
 monochromator are:
\begin{description}
\item[MakeMono name M1 M2 M3 M4] This command creates a crystal monochromator object. Such a
monochromator object is necessary for the usage of the wavelength or energy
variables. The parameter name defines the name of the monochromator object
in the system. M1 and M2 are the names of the Theta and two Theta motors
respectively. M3 is an optional parameter defining a motor for driving the
horizontal curvature. M4 is an optional parameter defining a motor for
driving the vertical curvature of the monochromator.   
\item[MakeWaveLength nam mono] creates a wavelength variable nam.  The monochromator mono is used for 
adjustment.
\item[MakeEnergy nam mono] creates a energy  variable nam.  The
monochromator mono is used for adjustment.
\item[MakeOscillator name motor] Installs a module name which oscillates motor between the software 
 limits of the motor. This is useful for suppressing preferred 
 orientation effects on powder diffractometers.name then supports the 
 commands: start, stop, status which are self explanatory. 
\end{description}

\subsection{Reoccuring Tasks}


Sometimes it may be necessary to execute a SICS command at regular
time intervalls. This can be achieved with the sicscron command:
\begin{description}
\item[sicscron intervall bla blab blab] This command installs a reoccuring task into SICS. The first
parameter is the intervall in seconds between calls to the SICS
command. Everything behind that is treated as the command to execute. 
\end{description}

\subsection{The SICS Online Help System}


SICS has a simple built in help system. Help text is stored in simple
ASCII text files which are printed to the client on demand. The help
system can search for help files in several directories. Typically one
would want one directory with general SICS help files and another one
with instrument specific help files. If help is invoked  without any
options, a default help file is printed. This file is supposed to
contain a directory of available help topics together with a brief
description. The normal usage is: help topicname . The help system
will then search for a file named topicname.txt in its help
directories.  

A SICS manager will need to configure this help system. A new
directory can be added to the list of directories to search with the
command:
\begin{verbatim} 
help configure adddir dirname
\end{verbatim}
The default help file can be specified with:
\begin{verbatim} 
help configure defaultfile filename 
\end{verbatim}
Each of these command given without a parameter print the current
settings. 

\subsection{Aliases in SICS}


SICS knows three different kinds of aliases: object aliases, 
runtime aliases and command
aliases. This is confusing but finds its explanation in the structure
of SICS internals. 

\subsubsection{Object Aliases}


An object alias is another name for a first class object installed
into the SICS interpreter. For instance a second name for a motor. For
instance the motor twotheta is quite often aliased to a4. Such an
alias can be used like a normal SICS objects. Even in commands which
access internal SICS interfaces like the drive command or
others. Object aliases are installed into SICS with the SICSAlias
command:
\begin{description}
\item[SicsAlias oldname newname] This command installs newname as alias for the object oldname.
\end{description}
 SicsAlias can only be used within initialization scripts. SicsAlias is 
 considered deprecated and can be replaced with the superior runtime 
 aliases described below.

\subsubsection{Runtime Aliases}


Runtime aliases are full object aliases which can be configured into the
 system at run time by a SICS manager.
The syntax looks like this:
\begin{description}
\item[DefineAlias aliasname SICSobject] This defines aliasname to be the alias for the SICS object SICSobject.
 It is not needed that SICSobject already exists. If SICSobject is already
 an alias, it is translated before definition.
 Multiple translation is possible, depending on the order of definition.
 When an alias is used, and it does not point to an existing object,
 the behaviour is the same as if an unknown object would have been used.
\item[DefineAlias aliasname] This command deletes the alias aliasname.
\end{description}
 
\subsubsection{Command Aliases}


Command aliases are shortcuts for lengthy commands. For instance one
might want to define A4LL as a shortcut for {\tt{}"{}}a4 softlowerlim{\tt{}"{}}. This is
just to save typing or adapt SICS to MAD users who  appear to have an
unlimited memory for 2-4 letter acronyms. It is possible to redefine a
SICS object with this for instance to define tt as an alias for
temperature. However if one tries to use tt in a drive command it will
fail because it is just a text replacement. A command alias can be
installed into SICS at any time with manager privilege   and the
command:
\begin{description}
\item[alias shortcut bla bla bla ....] This define shortcut as an alias for everything behind it.
\end{description}
A shortcut may take parameters.

\subsection{The AntiCollision Module}


In some cases motors have to be drive in a coordinated way. For instance,
 at TRICS, the chi motor may need to move first before omega can be 
 driven in order to avoid collisions. Or at the ECB instruments, only one 
 of eight motors in a rack can be driven at any given time. The anti collision
 module now allows to implement this. Anticollisions  pattern of 
 operation: Each 
 collaborating motor is registered with the anti collision module. When trying 
 to start such a motor, the anti collider just takes a note where it shoud go.
 On the first status check, a program is called which has to 
 arrange the running of the motors into a sequence. This sequence then is 
 executed by the anti collision module. The program which arranges the 
 motors into a sequence is a configurable parameter and usually implemented
 as a script in SICS own marco language. In the SICS initialization file this 
 requires the commands:
\begin{description}
\item[AntiCollisionInstall] Creates the anitcollision module.
\item[anticollision register motorname] Registers motorname with the anti collision module.
\item[anticollision script scriptname] This command configures the script which is responsible for 
 arranging the sequence of operations.
\end{description}
The script configured into anticollision is called with pairs 
 or motor names and targets as parameters, Example:
\begin{verbatim} 
sans2rack mot1 target1 mot2 target2 .....
\end{verbatim}
Within the anticollision script, the following command may be 
 used in order to define the sequence.
\begin{description}
\item[anticollision clear] Clears the sequence list
\item[anticollision add level motor target] Add motor with target to level in the sequence. 
\end{description}

% html: End of file: `gencom.htm'
% html: Beginning of file: `iscan.htm'

\section{The Internal Scan Commands}

\label{f11}
\subsection{Scan Concepts}


Scans in SICS involve an internal scan module and a lot of scripts which 
 wrap the internal scan module into a syntax liked by the users. 

The internal scan module  in SICS evolved a little over time. It turned 
out that scans
are a demanding  job for a programmer because of the plethora of
special scans people wish to perform and the many data file formats which
have to be supported. This requires a very high degree of
configurability. Under several refactorings the internal scan command
has grown to become:
\begin{itemize}
\item A controller for the scan process.
\item A container to store scanned variables and counts during the
process of a scan. This includes commands to store and retrieve such
values. 
\item A container for the configuration of the scan. A scan is
configured by specifying functions to be called at the various steps
during the scan. These are preconfigured to the standard scan
functions. An API is provided to replace some or all of the scan
functions by user defined ones.   
\end{itemize}
The internal scan object is augmented by a library of standard scan
functions. The transition to the new model is not yet clean in order
not to break to much old code. 

The standard scan command can be configured into SICS using the command:
\begin{description}
\item[MakeScanCommand name countername headfile recoverfil] MakeScanCommand initialises the SICS internal scan command. It will be
accessible as name in the system. The next parameter is the name of a valid
counter object to use for counting. The next parameter is the full pathname of
a header description file. This file describes the contents of the header of
the data file. The format of this file is described below. The parameter 
recoverfil is the full pathname of a file to store recover data. The internal
scan command writes the state of the scan to a file after each scan point.
This allows for restarting of aborted scans.   
\end{description}

The scan object (named here xxscan, but may have another name) understands
the following commands:
\begin{description}
\item[xxscan clear] clears the list of scan variables. Must be called before each scan with
different parameters.
\item[xxscan add name start step] This command adds the variable specified by the argument name to the
list of variables scanned in the next scan. The arguments start and step
define the starting point and the sptep width for the scan on this variable.
\item[xxscan run NP mode preset] Executes a scan. The arguments are: NP the number of scan points, mode
the counter mode to use (this can be either timer or monitor) and preset
which is the preset value for the counter. Scan data is written to an output
file.
\item[xxscan continue NP mode preset] Continues an interrupted scan. Used by the recovery feauture.
\item[xxscan silent NP mode preset] Executes a scan. The arguments are: NP the number of scan points, mode
the counter mode to use (this can be either timer or monitor) and preset
which is the preset value for the counter. The difference to run is, that
this scan does not produce an output file.
\item[xxscan recover] Recovers an aborted scan. The scan object writes a file with all data
necessary to continue the  scan after each scan point. If for some reason a
scan has been aborted due to user intervention or a system failure, this
scheme allows to continue the scan when everything is alright again. This
works only if the scan has been started with run, not with silent.
\item[xxscan getfile] This command returns the name of the current data file.
\item[xxscan setchannel n] Sometimes it is required to scan not the counter but a monitor. This
command sets the channel to collect data from. The argument n is an integer
ID for the channel to use.
\item[xxscan getcounts] Retrieves the counts collected during the scan.
\item[xxscan getmonitor i] Prints the monitor values collected during the scan for the
monitor number i
\item[xxscan gettime] Prints the counting times for the scan points in the current scan.
\item[xxscan np] Prints the number of points in the current scan.
\item[xxscan getvardata n] This command retrieves the values of a scan variable during the scan
(the x axis). The argument n is the ID of the scan variable to retrieve data
for. ID is 0 for the first scan variable added, 1 for the second etc.
\item[xxscan noscanvar] Prints the number of scan variables
\item[xxscan getvarpar i] Prints the name , start and step of the scan variable number i
\item[xxscan interest] A SICS client can be automatically notified about scan progress. This is
switched on with this command. Three types of messages are sent: A string
NewScan on start of the scan, a string ScanEnd after the scan has finished
and a string scan.Counts = \{109292 8377 ...\} with the scan values after each
finished scan point. 
\item[xxscan uuinterest] As above but the array of counts is transferred in UU encoded
format.
\item[xxscan dyninterest] As above but scan points are printed one by one as a list
containing: point number first\_scan\_var\_pos counts. 
\item[xxscan uninterest]  Uninterest switches automatic notification about scan progress off.
\item[xxscan integrate]  Calculates the integrated intensity of the peak and the variance of the
intensity for the last scan. Returns either an error, when insufficient scan
data is available or a pair of numbers. Peak integration is performed along
the method described by Grant and Gabe in J. Appl. Cryst. (1978), 11,
114-120.
\item[xxscan window \mbox{$[$}newval\mbox{$]$}] Peak Integration uses a window in order to determine if it is still in the
peak  or in background. This command allows to request the size of this
window (without argument) or set it (with argument giving the new window
size).
\item[xxscan simscan pos FWHM height] This is a debugging command. It simulates scan data with a hundred
points between an x axis ranging from 10 to 20. A gauss peak is produced
from the arguments given: pos denotes the position of the peak maximum, FWHM
is the full width at half maximum for the peak and height is its height. 
\item[xxscan command tclcommand] Sets the tcl command procedure to invoke at each scan point. See below
 for the description of user defined scans (Old Style). 
 Invoked without argument command
 returns the name of the current command procedure.
\item[xxscan configure mode] Configures the several possible scan modes for the scan
object. Currently there are two:
\begin{itemize}
\item {\bf standard}, the default mode  writing ASCII files.
\item {\bf amor}, a special mode the reflectometer AMOR which writes
NeXus files.  
\item {\bf script} Scan functions are overriden by the user.
\item {\bf soft} The scan stores and saves software zero point corrected 
 motor positions. The standard is to save the hardware positions as 
 read from the motor controller. 
\item {\bf user} configures the old style user overridable scans. 
\end{itemize}
\item[xxscan storecounts counts time mon1 mon2 ...] This stores an entry of count values into the scan data
structure. To be used from user defined scan functions. The scan
pointer is incremented by one. 
\item[xxscan storecounter ] Store the counts and monitors in the counter object configured for
the scan into the scan data structure. Increments the scan pointer by
one. 
\item[xxscan appendvarpos i pos ] Append pos to the array of positions for scan variable i. To be
used from user defined scan functions.
\item[xxscan callback scanstart \mbox{$|$} scanpoint \mbox{$|$} scanend] Triggers callbacks configured on the scan object. May be used by
user functions implementing own scan loops. 
\item[xxscan function list] Lists the available configurable function names. The calling style
of these functions is described in the next section about stdscan. 
\item[xxscan function functionname] Returns the currently configured function for functionname.
\item[xxscan function functionname newfunctionname] Sets a new function to be called for the function functionname in
the scan.  
\end{description}

\subsection{User Definable Scan Functions}

 
The last commands in the last section allowed to overload the
functions implementing various operations during the scan with user
defined methods. This section is the reference for these
functions. The following operations during a scan be configured:
\begin{description}
\item[writeheader] Is supposed to write the header of the data file
\item[prepare ] Prepare does all the necessary operations necessary before a scan
starts. 
\item[drive] Is called to drive to the next scan point
\item[count ] Is called at each scan point to perform the counting operation
\item[collect] Is called for  each scan point. This function is supposed to store
the scan data into the scan data structure. 
\item[writepoint] Is called for each scan point and is meant to print information
about the scan point to the data ile and to the user.
\item[finish] Is called after the scan finishes and may be used to dump a data file 
 or perform other clean up operations after a scan. 
\item[userdata] This is the name of a user defined object which may be used to
store user data for the scan.    
\end{description}
The exact invocations of the functions:
\begin{itemize}
\item writeheader scanobjectname userobjectname
\item prepare scanobjectname userobjectname
\item drive scanobjectname userobjectname point
\item count scanobjectname userobjectname point mode preset
\item collect scanobjectname userobjectname point
\item writepoint scanobjectname userobjectname point
\item finish scanobjectname userobjname
\end{itemize}
scanobjectname is the name of the scan object invoking the
function. This can be used for querying the scan
object. userobjectname is the name of a entity as specified as
userdata in the configuration. point is the number of the current scan point. 

\subsection{User Defined Scans(Old Style)}


This feauture allows to override only the counting operation during a scan. 
 This feauture is deprecated in favour of the user overridable scan functions 
 described above. As it is still used, however, here is the documentation
  for reference.

In some cases users wish to control the scan more closely, i.e. do
multiple counting operations at the same point etc. This is especially
true when magnets are involved. In order to do this a facility has
been provided which allows the user to specify a macro routine which
is called at each point. This macro routine then performs all
necessary operations and  then is responsible for storing its data. In
order to allow for this commands have been defined which allow to append 
a line to the scan data file and to store measured data in the scan data
structure. The last feature is necessary in order to make scan status
displays and scan analysis, such as center detection, work. The
following steps are required:
\begin{enumerate}
\item Write a suitable macro procedure for the actions required at each
scan point. The procedure signature looks like this:
\begin{verbatim} 
proc myScanPoint {point} {
}
\end{verbatim}
 And will be called with the number of the current scan point as
a parameter. Besides all usual Tcl and SICS commands the following
special commands may be used:
\begin{description}
\item[xxxscan line text] Appends all the text after line to the scan data file.
\item[xxxscan storecounts c1 c2 c3 c4 ...] Stores the first number given as count data, all the others as
monitor values in the internal scan data structure.
 \end{description}
 \item Test the procedure.
\item Switch the internal scan command command into user scan mode with
the command:
{\bf xxxscan configure user}
\item Assign your procedure to the internal scan command with the
command: {\bf xxxscan command myScanPoint}
\item Use normal scan commands for doing your scan.
\item Switch the internal scan command into normal mode with the
command:
{\bf xxxscan configure standard}.
\end{enumerate}
In all this replace xxxscan with the name of the internal scan
command. 

\subsection{The Scan Command Header Description File}


As if all this configurability is not enough, there is another 
 level of configurability. 
The SICS internal scan command allows to configure the contents of 
 the header of
the ASCII scan data file through a template header file. This is only 
 possible when the scan functions are left in their default configuration. 
 If scan functions are overloaded it is the users repsonsability to take
 care of data file writing.
This section describes
the contents of the template file. This header description file 
 consists of normal
text mixed with a few special keywords. The normal test will be copied to
output verbatim. The keywords indicate that their place will be replaced by 
values at run time. Currently only one keyword per line is supported. 
Keywords recognized are:
\begin{description}
\item[!!DATE!!] Will be replaced with the file creation date.
\item[!!VAR(name)!!] Will be replaced with the value of the SICS variable name.
\item[!!DRIV(name)!!] Will be replaced with the value drivable variable name. Drivable variables are
all motors and all variables which may be used in a drive or run command.
\item[!!ZERO(name)!!] Will be replaced with the value of the softzero point for motor name.
\item[!!FILE!!] Will be replaced by the creation name of the file. 
\end{description}
Please note that text behind such a keyword in the line will not be copied to
the output.

\subsection{Differential Scans}


When aligning or when searching peaks a very fast scan is
required. This is the differential scan. It starts a motor and
collects counts while the motor is running. The counts collected are
the monitor normalized difference to the previous reading. This
functionality can be configured into SICS with the command:
\begin{verbatim} 
MakeDiffScan 
\end{verbatim}
 in the configuration file. An optional parameter defines
another name then diffscan (the default) for this object. Differential
scans can only be run against one motor as it cannot be guaranteed that
motors involved in a coordinated movement operate at the same speed 
 without mechanical coupling. The
procedure to use diffscan is:
\begin{itemize}
\item Configure a scan variable into a SICS scan object: xxscan add var
start step
\item Run diffscan as: diffscan scanobjectname end\_position\_of\_scan
This runs the differential scan. Scanobjectname is the name of a SICS
internal scan object.   It will be used to store the results of the
scan. While the scan is running some basic information is printed. The
scan will range from the start given in the xxscan add command to the
end position given in this call.  
\end{itemize}
The diffscan object has two configurable parameters:
\begin{description}
\item[monitor] The monitor number to normalize against. For maximum precision
this should be a monitor with a lot of intensity on it.
\item[skip] The number of SICS main loop cycles to skip between readings. This
can be used to control the amount of data  generated during a
differential scan. This may become a problem if there is fast hardware.
\end{description}
 A word of warning: positions found in differential scans may not be
totally correct. The differential scan might even miss peaks when the
relationship between motor speed and sampling rate is bad.  

Diffscan is usally wrapped in a common script command:
\begin{description}
\item[fastscan motor start stop speed] which does a fast scan for motor from start to stop. Before the scan
 the motors speed is set to speed. The motor is set to its original speed
 after termination of the scan.
\end{description}
This script can be copied from one of the older instrument command files. 

\subsection{Peak Analysis}


There are several other feautures which can be configured into SICS 
 which interact very closely with the scan module:
\begin{description}
\item[MakePeakCenter scancommand] MakePeakCenter initialises the peak analysis commands peak and center. The
only parameter is the name of the internal scan command.
\end{description}

\subsection{Common Scan Scripts}


There exists a library of script functions around the scan module which are 
 commonly used. They provide an object oriented wrapper around the internal 
 scan command and the {\bf cscan} and {\bf sscan} commands. These 
 commands can be made available by including the scancommand.tcl file into
 the instruments configuration file. 
% html: End of file: `iscan.htm'
% html: Beginning of file: `nxscript.htm'

\section{Scripting NeXus Files}

\label{f12}
This section describes the scripting interface to NeXus
files, called nxscript. Scripting the generation of NeXus files has
the  advantage that
it can be customised very quickly to special needs. Moreover it might
help to reduce the amount of instrument specific code required for an
instrument. This scripting interface uses the NeXus dictionary API for
the actual writing process. This has the following consequences: 
\begin{itemize}
\item The interface needs two filenames: the
NeXus filename and the dictionary filename when opening files. 
\item Writing commands have the general form: alias object. This means
that object is written to the NeXus file using the specified alias. 
\item Another property is that some writing commands write several bits
of information in one go. In such cases the aliases for the additional
bits are derived from the base alias by appending specific
strings. Thus dictionary files need to have a special form for this
scripting interface to work.
\item Nxscript also tries to figure out the dimensions of
multidimensional datasets such as histogram memories by itself. In
such cases the dimension attribute in the dictionary file must be
omitted.
\item Nxscript assumes the following policy for data writing:
irrespective of errors write everything you can. Thus this interface
will complain bitterly and verbosely if something does not work, but
never return an error. 
\end{itemize}
   
\subsection{Usage}


Before this facility can be used nxscript has to be installed into the
SICServer from the instrument configuration file. This is done through
the command:
\begin{description}
\item[MakeNXScript ?name? ] This creates a NeXus scripting object. If the name is omitted, an
object named nxscript is created. If a name is given, this name is
used for the scripting object. Having scripting objects with different
names is also the only possibility to have more then one NeXus file
writing operation going at a given time. 
\end{description}
In the following sections it is assumed that an object {\bf nxscript}
had been configured into SICS.  

\subsubsection{File Opening and Closing}


\begin{description}\item[nxscript create5 nexusFile dictFile] Creates a new NeXus file based on HDF-5 with the name
nexusFile. The dictionary file dictFile is used.
\item[nxscript create4 nexusFile dictFile] Creates a new NeXus file based on HDF-4 with the name
nexusFile. The dictionary file dictFile is used.
\item[nxscript createxml nexusFile dictFile] Creates a new NeXus file based on XML with the name
nexusFile. The dictionary file dictFile is used.
\item[nxscript reopen nexusFile dictFile] Reopens  an existing NeXus with the name
nexusFile for modification or appending. 
The dictionary file dictFile is used.
\item[nxscript close] Closes the current NeXus file. This command MUST be given at the
end of each script in order to make sure that all data is written
properly to disk. 
\end{description}
 
\subsubsection{Writing Things}


\begin{description}\item[nxscript puttext alias bla bla bla ....] Writes everything after alias as text data to the alias. The
definition string for the alias should not contain a dimension
description, this is automatically appended.
\item[nxscript putfloat alias value] Writes a single floating point value to alias alias. 
\item[nxscript putint alias value] Writes a single integer value to alias alias.
\item[nxscript updatedictvar alias value] Updates the dictionary value alis to value. 
\item[nscript putmot aliasName motorName] Writes the position of the motor motorName into the NeXus file as
described by aliasName. Theposition is a zero point corrected position. If
another alias   aliasname\_null exists in the dictionary, the zero
point of the motor is also written to file.
\item[nxscript putcounter aliasBase counterName] Writes counter data to a NeXus file. Data is taken from the single
counter counterName. What is written depends on the aliases present in
the dictionary file:
\begin{description}
\item[aliasBase\_preset] The preset value.
\item[aliasBase\_mode] The counter mode
\item[aliasBase\_time] The actual time counted, without breaks due to insufficient beam.
\item[aliasbase\_00 ... aliasBase\_09] The monitor readings for monitors 0 to 9. Please note that 00
would denote the normal counting tube at a scanning type of
experiment.   
\end{description}
\item[nxscript puthm hmAlias hmName ?start? ?length?] Writes data from the histogram memory hmName to a NeXus file using
the alias hmAlias. Nxscript automatically updates the dim0, dim1, ..., timedim 
dictionary variables. Thus these can be used to define the dimensions in the
dictionary file.
If the optional  parameters start and end are given, a
subset of the data is written. It is the users responsability that the
values requested make sense to the histogram memory. In the case of
subset writing, the dimensions have to be specified in the definition
string belonging to the alias. Nxscript sets a variable timedim in the
dictionary though which contains the length of a time binning if
appropriate. This is a special feauture for writing extra detectors at
SANS and AMOR.
\item[nxscript puttimebinning aliasName hmName] Writes the time binning at histogram memory hmName to file using
the alias aliasName. The length of the time binning data is
automatically appended to the definition string for the alias.   
\item[nxscript putarray aliasName arrayName length] Writes the Tcl array arrayName to file using the aliasName. The
definiton string belonging to aliasName does not need to contain a
-dim argument as this is set by this routine. The parameter length is
the length of the array. Only rank 1 arrays are supported. 
\item[nxsript putglobal attName bla bla bla] This writes an global attribute attName. Everything after attName
is concatenated to a string which then respresents the value of the
attribute.  
\item[nxscript makelink targetAlias victimAlias] This creates a symbolic link for victimAlias in the group
designated by targetAlias. 
\end{description}

\section{Automatic Updating of NeXus Files}


Some instruments perform measurements for quite long counting
times. In such cases it is advisable to save the data measured so far
to file in order to protect against hardware or software failures. To
this purpose an automatic file upgrade manager is provided. On
installation the automatic update object is connected wth a counting
device through the the callback interface. This makes sure that the
update manager is automatically notified when counting starts or
finishes.  

\subsection{Prerequisites for Using the Automatic Update Manager}


In order to use automatic updating, three programs must be
provided. Each of these programs can be a script which uses the
nxscript facility. It can also be a SICS command. 
\begin{description}
\item[startScript] This program is supposed to write the static part of the file. It
is called once when the file is created.
\item[updateScript] This program is supposed to create and update the variable data
elements in the NeXus file. This is called frequently.
\item[linkScript] This program is supposed to create the links within the NeXus
file. This is called once after startscript and updateScript have been
run. 
\end{description}

\subsection{Installing Automatic Update}


An automatic update object is installed into SICS with:
\begin{verbatim} 
updatefactory name countername
\end{verbatim}
name is a placeholder for the name under which SICS knows the
automatic update object. name is available as a SICS command later on.
 countername is a placeholder for a counter
object (counter or HM) which triggers automatic updating of NeXus
files. This object has to support both the countable and callback
interfaces of SICS. Suitable SICS objects include counter and
histogram memory objects. 

\subsection{Configuring Automatic Update}


The SICS command created with updatefactory (see above) supports a few
parameters which allow for the configuration of the whole
process. Parameters follow the normal SICS syntax. Futhermore there is
a subcommand list, which lists all configuration
parameters. Supported parameters are:
\begin{description}
\item[startScript] The program supposed to write the static part of the file. 
\item[updateScript] The program supposed to create and update the variable data
elements in the NeXus file. 
\item[linkScript] This program supposed to create the links within the NeXus
file. 
\item[updateintervall] The time intervall in seconds between updates. The defualt is
1200, eg. 20 minutes. 
\end{description}

% html: End of file: `nxscript.htm'
\section{Instrument Specific SICS Initializations}
% html: Beginning of file: `four.htm'

\subsection{Initialization for Four Circle Diffractometers}

\label{f13}
This section describes how the modules which are special for a four 
 circle single crystal diffractometer are configured into SICS. The 
 following feautures are available:
\begin{description}
\item[MakeHKL theta omega chi phi] MakeHKL creates the hkl command for the calculation of settings for a four
circle diffractometer. The four parameters are the names of the motors
driving the two theta, omega, chi and phi circles of the diffractometer.
These motors must already exists before this command may succeed.
\item[MakeHKLMot hkl] Creates the drivable H, k, l virtual motors using hkl, an 
 object created by  MakeHKL for calculations.
\item[MakeDifrac tth om chi phi cter] This command installs the Difrac subsystem into SICS. Difrac is a
whole F77 package for controlling a four circle
diffractometer. Afterwards Difrac commands are available in SICS with
the prefix dif, for example dif ah calls the difrac ah command. Difrac
is described in more detail elsewhere. The parameters are the four
circle motors two theta, omega, chi and phi and the counter. This is no longer
 maintained. 
\item[MakeMesure name scanobject hklobject omega s2t fileroot datanumberobject] MakeMesure installs the single counter four circle diffractometer
measurement procedure into SICS. It will be accessible as object name
afterwards. MakeMesure takes a lot of parameters:
\begin{description}
\item[scanobject] The name of the internal scan object.
\item[hklobject] The name of the object which does crystallographic calculations.
\item[omega] The name of the motor driving omega.
\item[s2t] The name of the two theta motor for use in  omega two theta scans.
\item[fileroot] The full path to the data file directory without final /
\item[datanumberobject] The name of the SICS data number object for creating unique file
numbers.
\end{description}
\item[MakeUBCalc name hklobject] This installs a UB matrix calculation module with the name name 
 into SICS. The second parameter is a hklobject as created with MakeHKL 
 to which any calculated UB's can be transferred.
\item[MakeHklscan scanobject hklobject] Installs the hklscan command which allows to scan in reciprocal space.
Scanobject is the name of SICS internal scan object, hklobject the name of a 
 reciprocal space calculation object as configured with MakeHKL.
\item[MakeTRICSSupport] Installs a command, tricssupport, which helps the TRICS status 
 display. 
\end{description}

Commands implemented by tricssupport:
\begin{description}
\item[tricssupport oldframe file idet nFrame] Loads and sends the frame nFrame of detector idet from file file in 
 UUencoded form.
\item[tricssupport interest] Enables this connection to receive notifications whenever a new frame 
 of data had been written
\item[tricssupport newframe] Called from scripts. Triggers sending new frames to all registered 
 connections. 
\end{description}
There are also a lot of scripted command available for four circle 
 diffractometers. These may be copied from tricscom.tcl. These include:
\begin{description}
\item[four] print the four all important angles
\item[tricsscan start step np] Omega scan with a PSD
\item[psdrefscan file step np mode preset] Read reflections from file, drive to them, do a omega scan with tricsscan
 using the parameters specified. 
\item[detscan start step np] Do a detector calibration scan.
\item[phscan start step np] Do a phi scan
\item[hklscan2d] Scanning reciprocal space with the area detector
\item[scan2d] Configure SICS for general scanning with the PSD. This is meant
 to supersede many of the special scans above.
\item[scan1d ] Configure SICS for general scanning with the single detector.
\end{description}

% html: End of file: `four.htm'
% html: Beginning of file: `tas.htm'

\subsection{Triple Axis Spectrometer Specific Commands}

\label{f14}
One aim for the implementation of the triple axis spectrometer in SICS 
 was to implement as closely as possible the command set of the ILL program 
 MAD. For this, there are two implementations: an older one where 
 most things werde done in C-code. And a newer one which implements 
 a relaxter MAD emulation.  The problem with the MAD emulation is that
 MAD relies on the order of variables and motors in memory. The newer
 MAD emulation obeys this only for the qh, qk, ql and en variables. 
 This section describes the newer more portable TAS setup. There are
 some C-modules and a lots of scripts which implement the MAD emulation.

The TAS requires the following initializations in its instrument file:
\begin{description}
\item[MakeTasUB tasub] Installs the TAS crystallographic calculation module into SICS. It will
 have the name tasub (recommended).
\item[MakeTasScan iscan tasub] Installs the module with the TAS specific scan functions into SICS. The
 TAS implements its own data format resembling the ILL TAS data format.
\end{description}
Moreover it is required to add the peak center module, drive, exe and a lot of 
 variables: polfile, alf1-4, bet1-4, ETAM ETAS ETAA.
 
The scripts for the MAD emulation live in the file tasubcom.tcl. This file 
 will need little editing in order to cope with another triple axis machine,
 just a couple of path variables will need to be changed.   
% html: End of file: `tas.htm'
% html: Beginning of file: `amor.htm'

\subsection{Special Commands for the Reflectometer (AMOR)}

\label{f15}
There are some special command initializations for the reflectometer AMOR. 
 These commands are most likely not portable to other instruments because 
 they encompass the special geometry at AMOR and the AMOR development has
 not fully matured.  The following initialization commands are available:
\begin{description}
\item[MakeAmor2T name da] This creates a virtual two theta motor for the reflectometer
AMOR. The two parameters are the name of the object in SICS and a
Tcl-array with  configuration parameters. The needed elements of this
array are:
\begin{description}
\item[mom] The monochromator omega motor.
\item[som] The sample omega motor.
\item[coz]  The height movement of the detector.
\item[cox]  The movement of the detector along the optical bench.
\item[stz ]  The height movement of the sample connected to the omega circle.
\item[soz]  The height movement of the sample table.
\item[d4b] The motor moving the whole diaphragm 4 up.
\item[d5b] The motor moving the whole diaphragm 5 up.
\item[com] The omega mevement of the detector.
\end{description}
    An example:
\begin{verbatim} 
set a2t(mom) mom
set a2t(som) som
set a2t(coz) coz
set a2t(cox) cox
set a2t(stz) stz
set a2t(soz) soz
set a2t(d4b) d4b
set a2t(d5b) d5b
set a2t(com) com
MakeAmor2T a2t a2t
\end{verbatim}
creates a virtual AMOR two theta motor with the name a2t.
\item[MakeStoreAmor hm] Creates an object for writing reflectometer data files. The name
of the command is storeamor. The parameter hm denotes the histogram
memory object.
\item[MakeAmorStatus name scan hm] This creates a helper object for the reflectometer status display
with name name. This object performs some operations on behalf of the
status display for the reflectometer AMOR. The parameter scan denotes
the name of the scan object. The parameter hm the name of the
histogram memory object. 
\end{description}

\subsubsection{AMOR Status Display Commands}


MakeAmorStatus creates a SICS command which is used by the AMOR status
 display for displaying proceesed data, especially in TOF-mode. This module
 provides the following commands:
\begin{description}
\item[amorstatus interest] This registers this connection for receiving automatic
notifications. Automatic notifications send are:
\begin{description}
\item[SCANSTART]  At scan start a message {\bf ScanClear} is sent followed by the
uuencoded new x-axis for the plot.
\item[SCANPOINT] At each scan point the arrays of counts in both detector are sent
in uuencoded form labelled arrow\_spinupup and arrow\_spinuplo. 
\item[COUNTSTART] The start of counting on the histogram memory. Send a message
{\bf TOFClear} and then the uuencoded time binning labelled
arrow\_time. 
\item[FILELOADED] activated each time user defined model data is loaded into the
SICS server. This data gets send as arrow\_name in uuencoded form. Both
x- and y-axis are sent in floating point. 
\end{description}
Please note that floating point data is transformed to fixed point by
multiplication of 65653 before transfer. The first number in each
uuencoded message is an integer describing the length of the data. In
case of double data such as fileloaded the y-data follows immediatetly
after the x-data. Also the appropriate data is automatically sent after
the interest command.
\item[amorstatus collapse] sums all counts in all detectors in time and sends the data back
as an uuencoded image. The first two numbers in the message define the
dimensions of the data. 
\item[amorstatus sample name x1 x2 y1 y2] Sums the detector counts on an area defined by the rectangle x1,
x2, y1, y2. The length of this is the time binning. The data is sent
back in uuencoded form labelled arrow\_name. 
\item[amorstatus clear]  Clears all user loaded data. 
\item[amorstatus load filename scale]  loads user defined data for distribution to the status display
clients. The y data is scaled according to the scale factor provided. 
\item[amorstatus projectytof] Returns a UUencoded 2D array of y against TOF. 
\end{description}

% html: End of file: `amor.htm'
% html: Beginning of file: `sans.htm'

\subsection{SANS Special Commands}

\label{f16}
Some special initializations for SANS Instruments:
\begin{description}
\item[ MakeMulti name]  SANS uses a special syntax feature where several motors are grouped into a
 component group. For example beamstop or detector. MakeMulti creates such a
group with the name name. Once such a group has been created, it has to be 
configured. For this a few configuration commands are available:
\begin{description}
\item[name alias motname compname]  This command makes motor motname available as component motor compname.
For example: {\bf bs alias bsx x} makes motor bsx available as x in the beamstop
group. Then the bsx motor can be driven by the command {\bf bx x = 12.}.
\item[ name pos posname motname value motname value ....]  The group command supports the notion of named positions. This means that
a special combination of angles can be accessed through a name. This commands
defines such a named position with the name posname. posname is followed by pairs
of motorname value which define the position.
\item[name endconfig] Once a group has been completely defined the configuration process must be 
ended with endconfig. 
\end{description}
\item[MakeSANSWave name velo\_name] > Installs a velocity selector wavelength variable into SICS. The
variable will have the name given as first parameter. Usually lambda is a
good idea. The second parameter, velo\_name, is the name of the velocity
selector which is controlled by this wavelength variable. This module contains 
 a hard coded formula which may only be applicable to the SANS at PSI. 
\item[MakePSDFrame] This installs a command into SICS which allows to retrieve a detector 
 image from the histogram memory, even in TOF-mode. 
\end{description}
Many other commands for controlling collimators, attenuators, beamstops 
 and shutters are implemented in Tcl. These commands use non standardizable 
 hardware such as the Siematic SPS. 
% html: End of file: `sans.htm'
% html: Beginning of file: `focus.htm'

\subsection{Special FOCUS Initializations}

\label{f17}
These initailizations are special to the FOCUS instrument:
\begin{description}
\item[InstallFocusmerge datafile] Installs the module which is responsible for merging focus data into
 merged detector banks. 
\item[MakeFocusAverager average hmc] Installs the average command and the focusraw command into SICS which 
 are used by the FOCUS status client in order to  display processed 
 histogram memory data. 
\end{description}

\subsubsection{Special Internal FOCUS Support Commands}


\begin{description}\item[focusraw bankid] Dumps in UUencoded form the content of the detector bank bankid. This is
required in order to add the TOF-binning to the data and in order to handle
 the virtual merged detector bank which is built from contributions of the
 three physical detector banks.
\item[average start stop bankid] Sums the detectors between start and stop of detector bankid into a 
 histogram. A standard display in the status client.
\item[focusmerge puttwotheta nxscriptmod bankname alias] Writes two theta values for the detector bank bankname into 
 the file described by the nxscript module nxsciptmod to the 
 alias alias. A helper function for data file writing.
\item[focusmerge putmerged nxscriptmod alias] Writes the virtual merged detector bank into alias in
 nxscriptmod.
\item[focusmerge putsum nxscriptmod bankname alias] Writes the summed counts for detector bank bankname under alias
 into nxscriptmod.
\item[focusmerge putelastic nxscriptmod alias theoelastic] Calculate the position of the elastic line and write it to alias in 
 nxscriptmod.  If no elastic line can be calculated, the theoretical 
 elastic line, theoelastic, is used. 
\end{description}
 
% html: End of file: `focus.htm'

% html: Beginning of file: `macroman.htm'

\chapter{Programming SICS Macros}

\label{f18}
The SICS server has a built in macro language. This macro language is basically
John Ousterhout's Tool Command Language Tcl. Tcl is described elsewhere.
A sound knowledge of Tcl is required for programming SICS macros. The SICS macro
language can be used for the following purposes:
\begin{itemize}
\item Add hoc measurement procedures.
\item Trial measurement procedures.
\item Syntax adaptions to one's own favourite syntax.
\item Building of more complex commands from the SICS primitives.
\end{itemize}
The general procedure for defining a macro requires defining the macro in a new
file, source this file from the configuration script and the use of the Publish 
command to make it available. New commands can best be defined as Tcl procedures,
 but the obTcl object oriented extension to Tcl is known to work as well. The SICS
macro language allows to access:
\begin{itemize}
\item Most Tcl commands.
\item All SICS commands.
\end{itemize}
In the following sections a few pecularities of the SICS macro system will be
discussed.

\section{Input/Output}


It would be quite verbose and confusing for the user if all output from SICS
commands called from a macro would appear on the screen during macro execution. 
Therefore all
normal SICS output to a client is suppressed while executing a macro. Except
 error messages and warnings which will always be written to the 
client executing the macro. The output of a SICS command is available within the
macro script  through the normal Tcl mechanism as a return value. This allows for
processing of SICS output within a macro. If the  output to the client executing
the macro is required this can be done with the ClientPut command, detailed in the
user documentation.

\section{Error Handling}


Tcl has the feature that it aborts execution of a script when an error occurs.
If a macro script needs to handle errors either from Tcl or from SICS commands
this can be achieved by using the Tcl catch mechanism.   

If things are seriously wrong or the users wishes to interrupt an operation 
 SICS interrupts are used. Scripts implementing measurement procedures may 
need to test and even modify interrupt values. 
A script can inquire the current interrupt value of the 
connection with the command {\bf GetInt}. If a script can handle an error condition
it may set the interrupt on the connection object with the {\bf SetInt} command.
The textual representations of interrupts for these commands are:
continue, abortop, abortscan, abortbatch, halt, free, end. 

\section{Interacting with SICS within a Script}


There exist a few commands which allow to inquire or manipulate SICS
internals. Most of these commands are only available in macro scripts.
\begin{description}
\item[SICSType thing.]  SICSType lets SICS find out if thing has some meaning within SICS. Possible return 
values are: DRIV for a drivable variable, COM for a SICS command, NUM for a numeric
value and TEXT for anything else.
\item[SICSBounds var newval] SICSBounds checks if newval violates the hardware or software limits of
the variable var. 
\item[SetStatus newval] SetStatus sets the SICS status line to a new value. Possible values for
newval are:  Eager, UserWait, Count, NoBeam, Paused,  Driving, Running,
Scanning, Batch, Halt, Dead.
\item[SICSStatus var] SICSStatus returns a integer value representing the current status of
the object var. var must be a drivable or countable object. The integer code returned
are defined in the SICS programmers documentation. 
\end{description}
 
\section{SICS Interfaces in Tcl}


Work has begun to implement SICS internal interfaces in Tcl. This opens the
 port for writing even device drivers in Tcl. Another use is to define 
 virtual motors quickly in Tcl. At the time of writing, July 2005, this 
 is only developed for the object interface and the drivable interface.
 For the meaning of internal SICS interfaces please consult the SICS
 programmers documentation. Be warned: with the feautures described in this
 section, you can mess up SICS badly.    

\subsection{The Object Interface}


\begin{description}\item[MakeTclInt name] Creates an object name. This object then understands the following 
  commands:
  \begin{description}  \item[ name savescript scriptname  ] Configures a script which will be called when it is time to dump
      the status of the SICS server. This script will be called with the
      name of the object as its only parameter.
  \item[name backup bla bla bla....  ] To be used from savescripts. Writes everything behind backup into the
      status file.
  \end{description}
  The use of this facility is to place special commands into the status file 
  which may, for instance, request calculations to be made or drive parameters
  not caught in the standard SICS objects to special values. For example: 
  at SANS2 this is used in order to store attenuator and collimator 
  values.  Both are implemented as scripted commands and thus do take part
  in the standard SICS object saving scheme. 
\end{description}

\subsection{Overriding the Drivable Interface with Tcl}


The drivable interface of any given drivable object can be overriden with 
 tcl functions. This includes an object created with MakeTclInt. The syntax is:
\begin{description}
\item[TclReplaceDrivable objname key scriptname tclName] This replaces the drivable interface function defined by key with the
 script scriptname in the driveable interface of the SICS object object. 
 tclName is the name of an arbitrary Tcl object which can hold user data.
 Possible function keys and their function signatures are:
 \begin{description} \item[halt ]  haltscript, no parameters 
 \item[checklimits ] checklimitsscript targetvalue
 \item[setvalue ] setvaluscript targetvalue
 \item[checkstatus  ] checkstatusscript, no parameters
 \item[getvalue ] getvaluescript, no parameters
 \end{description}
 All procedures, excpet getvaluescript, are supposed to return the 
 approriate SICS return codes (HW*) as integer numbers. Getvaluescript
 is supposed to return the position of the device.
\item[TclDrivableInvoke objname key] A debugging aid: Invokes the scripted function denoted by key of the 
 object objname and prints the results. The function keys are the same
 as given above.
\end{description}
 
% html: End of file: `macroman.htm'

% html: Beginning of file: `mcstas.htm'

\chapter{The McStas SICS Interface}

\label{f8}
It is useful to drive a simulation of an instrument with the same interface as is used at
the original instruments. One of the better packages for performing simulations of neutron
scattering instruments, including samples, is McStas. This section describes the SICS
interface to McStas simulations. The interface consists of three parts:
\begin{itemize}
\item A McStas controller module which controls the actual simulation.
\item A McStas reader which is responsible for reading simulated data into 
 SICS counters and histogram memories. 
 \item Counter and histogram memory drivers which redirect their actions to the 
  McStas controller module. 
\end{itemize}
The general ideas is that all parameters are handled through the normal SICS simulation 
 drivers. The counting operations, however, are linked with the McStas simulation. In order
 to be portable, many aspects are controlled by scripts. These scripts are configured at the 
 McStas Controller. Several scripts must be defined:
\begin{description}
\item[startmcstas] This script will be invoked when counting starts and has to collect the necessary
 settings from SICS, construct a McStas command line and start the simulation. As a return 
  value this script has to return the PID of the started mcstat process.
 \item[mcstastest pid ] Tests if the McStas simulation is still running.
 \item[mcstasdump pid ] Has to send a signal to McStas which causes it to dump its data without terminating. 
 Current versions of McStas do this on receiving the USR2 signal. 
 \item[mcstasstop pid ] Stops the McStas simulation. 
 \item[mcstasread ] Reads the McStas simulation output and transfers monitor and histogram memory data  
 into the appropriate SICS objects.
\end{description}

\section{McStas Requirements and SICS Requirements}


In order for the McStas SICS interface to work the McStas simulation has to be configured 
in a certain way:
\begin{itemize}
\item All parameters which have to pass between SICS and McStas have to be declared as 
 simulation parameters in the DEFINE INSTRUMENT section of the instrument definition file.
 Alternatively SICS can write the data to be passed to McStas into a file. But then this
 file must be read in the INITIALIZE section of the instrument definition and values must
  be assigned to the appropriate McStas variables. 
\item In order for the NeXus-XML based reading to work McStas must dump its data into a single file: 
 use the {\bf -f filename} option. The format must be {\bf  --format=XML}. 
 \item  In order to count on monitor, a modified monitor component, MKMonitor MUST be used in the
 simulation. This component writes the collected total counts into a file. This file is
 the read by SICS in order to determine the control monitor. Evaluating the McStas dump \mbox{$\backslash$}
 file each time proved to be to inaccurate. The name of the file containing the monitor
  must be configured through: mccontrol configure mcmonfile name-of-file. 
 \item The mcstas simulation executable must be declared with allowexec in order to be able
  to start with the Tcl exec command.
\end{itemize}

\section{The McStas Reader}


In order to enable transfer from McStas result files into SICS objects a reader object is 
needed. This module supports XML formatted McStas files, with the output dumped into
one file. The McStas options to achieve this are: {\bf -f filename --format={\tt{}"{}}XML{\tt{}"{}}}
This module supports the following commands:
\begin{description}
\item[mcreader open filename] Opens a McStas simulation file for reading.
\item[mcreader close] Closes a McStas file after use. 
\item[mcreader insertmon path object monitornumber scale] This transfers a monitor value from a previously opened McStas file into a SICS
monitor field. The McStas field read is the values tag belonging to the component. The
parameters:
\begin{description}
\item[path] The path to the correct values field in the simulation file. The format is the same
as the path format for NXopenpath in the NeXus-API (which will internally be used). For
groups, the name attribute is used a path component.
\item[object] The counter object into which the monitor is read. This is a limitation, with the 
 this McStas interface only counters can store monitors. 
 \item[monitornumber ] Monitornumber is the monitor\mbox{$\backslash$} channel into which the value is to be stored.
 \item[scale ] Scale is an optional scale factor for the monitor. Real monitors have a 
  sensitivity of E-6, McStas monitors have an efficiency of 1.0. This factor allows to 
  correct for this.
\end{description}
\item[mcreader inserthm path hmobject scale] Inserts array data stored under path in the histogram memory array of hmobject which 
 must be a valid SICS histogram memory object. The path is the same as given for insertmon, 
 but of course the data part of the detector must be addressed. Scale is again an optional 
 scale factor which allows to scale the  McStas counts to real counts.
\end{description}
The mccreader module also supports reading data from any ASCII file into SICS. Mcreader 
close and open are not required then. For reading histogram memory data, the appropriate
 data has to be parsed into a SICSdata object first. Then
 data can be trasnferred using the following commands:
 \begin{description} \item[mcreader insertmondirect counter num value ] Assigns value to the monitor num at the counter object counter. Monitor 0 is the 
  actual counts data.   
 \item[mcreader inserthmfromdata hm data ] Inserts the data in the SICSData object data into the histogram memory hm. 
 \end{description}
 
\section{The McStas Controller}


The actual control of the {\tt{}"{}}counting{\tt{}"{}} operation of the McStas simulation is done by the
 McStas controller module in SICS. Internally this module implements the routines for 
 counting virtual neutrons. Towards the SICS interpreter, an interface is exhibited which 
 allows to configure and test the McStas controller. The McStas Controller delegates many 
 tasks to script procedures written in SICS's internal Tcl scripting language. This is done 
  in order to achieve a degree of generality for various types of instruments and in order
  to allow easier adaption to differing demands. This is the SICS interface implemented:
  \begin{description}  \item[mccontrol configure mcstart startscriptname  ] Configures the script which starts the McStas simulation. Startscriptname is the name
   of a Tcl procedure which collects the necessary information from SICS, builds a command 
line and finally starts the simulation. This script is expected to return either an error or
 the PID of the started process. Startscriptname will be called with the parameters mode and 
 preset which represent the counting characteristics.
 \item[mccontrol configure  mcisrunning runtestscriptname ] Configures the name of a script which tests if the McStas process is still running.
 Runtestscriptname is called with the PID as a parameter. This returns 0 in the case the 
  McStas simulation was stopped or 1 if it is still running.
 \item[mccontrol configure mcdump dumpscriptname ] Configures the name of the script which causes McStas to dump intermediate results.
 The script will be called with the PID of the started McStas process as a parameter.     
 \item[mccontrol configure mckill killscript ] Configure the name of a procedure which kills the current McStas simulation 
  process. KillScript will be called with the PID of the McStas simulation as a parameter.
 \item[mccontrol configure mccopydata copyscript ] This configures the name of a script which has the task to read the results of
  a McStas simulation and assign values to SICS monitors and histogram memories. 
  \item[mccontrol configure update updateintervallinseconds  ] This configures the minimum time between McStas dumps in seconds. The idea is that 
  SICS buffers values during a simulation run and does not interrupt the McStas process to 
  often. 
  \item[mccontrol configure update monitorscale  ] Configures the scaling factor to use on the monitor in monfile. Normal monitors have 
   a efficiency of 1E-6, the McStas monitor counts every neutron. This can be compensated 
   for by this scaling factor. Note that this scaling factor may be dependent on the 
   wavelength used. 
  \item[mccontrol configure mcmonfile filename  ] This configures the file which mccontrol is going to read in order to watch the
   simulation control monitor. 
  \item[mccontrol list  ] Prints a listing of the configuration parameters.
  \item[mccontrol run scriptkey  ] Invokes one of the scripts configure for testing purposes. scripkey can be one of:
   mcstart, mcisrunning, mcdump, mckill and mccopydata.  
   \item[mccontrol finish   ] This calls waitpid on the PID of the McStas process. This should be done in 
   the mckill script. Otherwise it may occur that the McStas simulation turns into
   a Zombie process. 
 \end{description}
Standard scripts for many of the script routines required are provided for the unix 
 environment in the file mcsupport.tcl. Please note, that all system executables called 
 from scripts must be registrered with SICS using the allowexec command. 
% html: End of file: `mcstas.htm'

\end{document}