\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}
DMC--User Manual \\
\end{huge}
Version 0.1, 8.7.1997\\
Dr. Mark K\"onnecke \\
Labor f\"ur Neutronenstreuung\\
Paul Scherrer Institut\\
CH--5232 Villigen--PSI\\
Switzerland\\
\end{center}
\clearpage
% html: Beginning of file: `sicsinvoc.htm'

\chapter{SICS Invocation}

\label{f0}

SICS is a client server system. This means there are at least two programs 
necessary to run the experiment. The first
is the
SICServer which does the actual instrument control work. A user rarely needs
to bother about this server program as it is meant to run all the time.
See instructions below if things go wrong. 

Then there are one to many client programs which interact with the
instrument  control server. These client programs implement the status
displays and a command line application which allows to influence the
course of the experiment. Graphical User Interfaces may be added at a
later time. 
The user has only to deal with
these SICS client programs. SICS Clients and the SICServer communicate
with each other through TCP/IP sockets.   

Currently five SICS clients are available:
\begin{itemize}
\item  A command line control client which allows to control the measurement.
\item  A status display for DMC.
\item  A status display for TOPSI.
\item  A status display for SANS.
\item  A status display for FOCUS.
\item  A SICS variable watcher.
\end{itemize}


\section{Steps necessary for logging in to SICS}


The following actions have to be taken in order to interact with the
SICS server through a client:
\begin{itemize}
\item Start the client application.
\item Connect the client to a SICS server.
\item In case of command line clients: authorize yourself as
privileged SICS user.
\end{itemize}

\section{Starting SICS client applications }

 

These programs can be started on a DigitalUnix system by issuing the
following commands at the command prompt:
\begin{description}
\item[sics \&]  for the control client.
\item[powderstatus \&]  for the DMC status display client.
\item[topsistatus \&] for the TOPSI status display.
\item[sansstatus \&]  for the SANS status display.
\item[focustatus]  for the FOCUS status display.
\item[varwatch \&]  for the variable watcher.
\end{description}
On a PC you may find icons for starting the different programs on the
desktop.
Each of these clients has usage instructions online which can be displayed
through the help/about menu entry. 

\section{Connecting}



After startup any SICS client is not connected to a SICS server and thus not
active. A connection is established through the connect menu of the client.

\section{Authorization}



SICS is a multi user instrument control system. In order to  prevent
malicious manipulations of the instrument SICS supports a hierarchy of user
rights. In order to run an experiment you need at least user level privilege.
In order to achieve this privilege you have to invoke the User Parameter/Set
Rights dialog. There you have to enter the apropriate username and password
kindly provided by your instrument scientist.

\section{Restarting the Server}



The SICS server should be running all the time. It is only down if something
went wrong. You can check for the presence of the SICS  server by loging in
to the instrument computer and typing {\bf CheckSICS} at the command
prompt. The output will tell you what is happening. If you need to restart
the SICS server log in as the instrument user at the instrument computer and
invoke the apropriate command to start the server. These are:
\begin{description}
\item[DMC] Computer = lnsa05,User = DMC
\item[TOPSI] Computer = lnsa03,User = TOPSI
\item[SANS] Computer = lnsa07,User = SANS
\item[TRICS] Computer = lnsa12, User = TRICS
\item[HRPT] Computer = lnsa11, User = HRPT
\item[FOCUS] Computer = lnsa13, User = FOCUS
\end{description}
For starting the SICS server type {\bf startsics}. This is a shell script
which will starts all necessary server programs. This script works only on
the instrument computer and in the appropriate instrument account.

 If all this does not help look under trouble shooting
SICS (cf.\ Section~\ref{f1}). 
% html: End of file: `sicsinvoc.htm'
% html: Beginning of file: `general.htm'

\chapter{General SICS commands}

\label{f2}
 

 This section describes general SICS concepts and SICS commands available to all instruments.

\section{Chapter Overview}



\begin{itemize}\item   This chapter starts with an overview over some basic (cf.\ Section~\ref{f3})  SICS  concepts.
\item  Than there are system (cf.\ Section~\ref{f4}) commands for closing the server, requesting status information etc.
\item  The Token command (cf.\ Section~\ref{f5}) for managing control access to
the SICS server. 
\item  A few commands permit to change (cf.\ Section~\ref{f6}) user rights, set output files  and the like.
\item  SICS has a built in macro (cf.\ Section~\ref{f7}) facility which is accessible through a few commands.
\item  Than there is the famous (cf.\ Section~\ref{f8}) LNS-R\"unbuffer system.
\item   Motors and parameters need to be drive (cf.\ Section~\ref{f9})n.
\item  Logging of client output to a file can be performed with the LogBook (cf.\ Section~\ref{f10}) command and the commandlog  (cf.\ Section~\ref{f11}).
\item  SICS has a facility to optimise (cf.\ Section~\ref{f12}) a peak with respect to several
parameters.
\end{itemize}

% html: End of file: `general.htm'
% html: Beginning of file: `basic.htm'

\section{Basic SICS concepts}

\label{f3}
 

\subsection{General structure}



 SICS is a client server system. The application the user sees is usually some form of client. A client has two tasks: the first is  to collect user input and send it to the SICS server who will  execute the command. The clients second task is to listen to the the server messages and display them in a readable format. This aoproach has two advantages: clients can reside on machines across the whole network thus enabling remote control from everywhere in the world. The second advantage is that new clients (such as graphical user interface clients) can be written in any feasible language without changes to the server.

\subsection{SICS Command  Syntax }



 SICS is an object oriented system. This is reflected in the command syntax. SICS objects can be devices such as motors or counters,  variables such as wavelength or Title and measurement procedures.  Communication with these objects happens by sending messages to the  target object. This is very simply done by typing something like: object message par1 par2 .. parn. For example, if we have  a motor called A1:\begin{verbatim} 
         A1 list
\end{verbatim}
 will print a parameter listing for the motor A1. In this example no parameters were needed. There exist a number of one-word commands as well. For 
compatability reasons some commands have  a form which resembles a function call such as:\begin{verbatim} 
           drive a1 26.54
\end{verbatim}
 This will drive motor a1 to 26.54. All commands are 
ASCII-strings and usually in english. SICS is in general CASE INSENSITIVE.
However, this does not hold for parameters you have to specify. On a unix
system for instance file names are case sensitive and that had to be
preserved. Commands defined in the scripting language are lower case by
convention.  

\subsection{Authorisation}



 A client server system is potentially open to unauthorised hackers which might mess up the instrument and your valuable  measurements. A known problem in instrument control is that less  knowledgeable user accidentally change instrument adjustments which should better be left fixed. In order to solve these two  problems SICS supports authorisation on a very fine level. As a user you have to specify a username and password in order to able to access SICS. Some clients already do this for you automatically.  SICS support four levels of access to an instrument:
\begin{itemize}
\item  {\bf  Spy } may look at everything, request any value, but may  not actually change anything. No damage potential here.
\item  {\bf  User } is privileged to perform a certain amount of operations necessary to run the instrument.
\item  {\bf  Manager } has the permission to mess with  almost everything.  A very dangerous person.
\item  {\bf  Internal } is not accessible to the outside world and is used to circumvent protection for internal uses. However some parameters are considered to be so critical that they cannot be changed during  the runtime of the SICS-server, not even by Managers.
\end{itemize}
 All this is stated here in order to explain the common error message: You are not authorised to do that and that or something along these lines.

\subsection{SICS variables}



 Most of the parameters SICS uses are hidden in the objects to which they belong. But some are separate objects of their own  right and are accessible at  top level. For instance things like Title or wavelength. They share a common syntax for changing and requesting their values. This is very simple: The command {\em  objectname } will return the value, the command {\em  objectname newvalue } will change the variable. But only if the authorisation codes match. 


\subsection{The SICS Command Line Client}


The most common client for controlling SICS is the {\bf SICS command line
client}.
This application can be started by typing the command:
\begin{verbatim} 
sics &
\end{verbatim}
at the Unix prompt. Before this program is ready to collaborate with you you
have to connect it to an instrument using the options in the connect
pulldown menu. The screen is roughly divided in three areas: The top area
shows all input to and output from the server. The middle area shows the
command history. At the lower end is a text entry field which allows to type
commands to the SICS server. For more information about this client consult
the online help of this application.   
% html: End of file: `basic.htm'
% html: Beginning of file: `system.htm'

\section{System Commands}

\label{f4}

{\bf  Sics\_Exitus }. A single word commands which shuts the server down. Only Managers may use this command.

 {\bf  wait time } waits time seconds before the next command is executed. This does not stop other clients from issuing commands.

 {\bf  ResetServer } resets the server after an interrupt.

 {\bf  Dir } a single word command which lists all objects available in the SICS system in its current configuration.

 {\bf  status } A single word command which makes SICS print its current 
status. Possible return values can be: 
Eager to execute  commands, Scanning, Counting, Running, Halted. Note that if  a command is executing  which takes some time to complete
 the server   will return an ERROR: Busy message when further commands are issued.

{\bf status interest} initiates automatic printing of any status change in the
server. This command is primarily of interest for status display client
implementors.

{\bf backup file} saves the current values of SICS variables and selected
 motor and device parameters to the disk file specified as parameter. The
 path to this files is relative to the SICS server directory. The format
 of the file is a list of SICS commands to set all these parameters again.

{\bf restore file} reads a file produced by the backup command described 
above and restores SICS to the state it was in when the status was saved with
 backup.
% html: End of file: `system.htm'
% html: Beginning of file: `config.htm'

\section{Configuration  Commands}

\label{f6}

 SICS allows to change the user rights of the current client server connection, control the amount of output a client receives and to specify additional logfiles where output will be placed. All this is accessed through the following commands:

 The SICS server logs all its activities to a logfile, regardless  of what the user requested. This logfile is mainly intended to help in server debugging. However, clients may register an interest in certain server events and can have them displayed. This facility is accessed via the {\bf  GetLog } command. It needs to be stressed that this log receives messages from {\bf  all } active clients. GetLog understands the  following messages:
\begin{itemize}
\item  {\bf  GetLog All } achieves that all output to the server logfile is also written to the client which issued this command.
\item  {\bf  GetLog Kill } stops all logging output to the client.
\item  {\bf  GetLog OutCode } request that only certain events will  be logged to the client issuing this command. Enables only the level specified. Multiple calls are possible.
\end{itemize}
 Possible values for OutCode in the last option are:
\begin{itemize}
\item  {\bf  Internal } internal errors such as memory errors etc.
\item  {\bf  Command } all commands issued from any client to the server.
\item  {\bf  HWError } all errors generated by instrument hardware. The  SICS server tries hard to fix HW errors in order to achieve stable  operations and may not generate an error message if it was able to fix the problem. This option may be very helpful when tracking dodgy devices.
\item  {\bf  InError } All input errors found on any clients input.
\item  {\bf  Error } All error messages generated by all clients.
\item  {\bf  Status } some commands send status messages to the client invoking the command in order to monitor the state of a scan. 
\item  {\bf  Value } Some commands return requested values to a user. These messages have an output code of Value. 
\end{itemize}

{\bf  config } allows to configure various aspects of the current client server connection. Basically three things can be manipulated:  The connections output class, the user rights associated with it,  and output files.

\begin{itemize} \item The command {\bf  config OutCode val } sets  the output code for the connection. By default all output is sent to the client. But a graphical user interface client might want to restrict message to  only those delivering requested values and error messages  and  suppressing anything else. In order to achieve this, this command is provided. Possible values Values for val are Internal,Command, HWError,InError,Status, Error, Value. This list is hierarchical. For example specifying InError for val lets the client receive all messages tagged InError, Status, Error and Value, but not HWError, Command and Internal messages.
\item Each connection between a client and the SICS server has user rights  assocociated with it. These user rights can be configured at runtime with the command {\bf  config Rights Username Password }. If a matching entry can be found in the servers password database new rights will be set.
\item Scientists are not content with having output on the screen. In order to
check results a log of all output may be required. The command {\bf  config
File name } makes all output to the client to be written to the file
specified by name as well. The file must be a file accessible to the server,
i.e. reside on the same machine as the server. Up to 10 logfiles can be
specified. Note, that a directly connected line printer is only a special
filename in unix.
\item {\bf  config close num} closes the log file denoted by num again. 
\item {\bf config list} lists the currently active values for outcode and user
rights.
\end{itemize}

  
% html: End of file: `config.htm'
% html: Beginning of file: `macro.htm'

\section{Macro Commands}

\label{f7}

 SICS has a built in macro facility. This macro facility is aimed at instrument managers and users alike. Instrument managers may provide customised measurement procedures in this language, users may write batch files in this language. The macro language is John Ousterhout's Tool Command Language (TCL). Tcl has control constructs, variables of its  own, loop constructs, associative arrays and procedures. Tcl is well documented by several books and online tutorials, therefore no details on Tcl will be given here. All SICS commands are available in the macro language. Some potentially harmful Tcl commands have been deleted from  the standard Tcl interpreter. These are: exec, source, puts, vwait, exit,gets and socket. The following commands allow access to the macro facility:

 {\bf  FileEval name } tries to open the file  name and executes the script in this file. Please note that the server is configured via such a file.

 {\bf  ClientPut sometext1 ... } writes everything after ClientPut to the client which started the script. Useful for output to a client from macro scripts.

{\bf  SICSType object } allows to query the type of the object specified by object. Possible return values are
\begin{itemize}
\item  {\bf  DRIV } if the object is a SICS drivable object such as a motor
\item  {\bf  COUNT } if the object is some form of a counter.
\item  {\bf  COM } if the object is a SICS command.
\item  {\bf  NUM } if the object is a number.
\item  {\bf  TEXT } if object is something meaningless to SICS.
\end{itemize}

 {\bf  SICSbounds var newval } checks if the new value newval lies within the limits for varaible var. Returns an error or OK depending on the result of the test.

 {\bf  SICSStatus var } SICS devices such as counters or motor may be started and left running while the program is free to do something else. This command allows to enquire the status of such a running device. Return values are internal SICS integer codes. This command is only of use for SICS programmers.

{\bf  SetStatus newval } allows to set the SICS status to one of: Eager, UserWait, Count, NoBeam, Driving, Running, Scanning, Batch Hatl or Dead. This command is only available in macros.

 {\bf  SetInt newval, GetInt } allow for the manipulation of interrupts from macro scripts. Not recommended! Possible return values or  new values are: continue, abortop, abortscan,  abortbatch, halt, free, end. This command is only permitted in macros. Should only be used by SICS programmers.
% html: End of file: `macro.htm'
% html: Beginning of file: `buffer.htm'

\section{R\"unbuffer Commands}

\label{f8}

 LNS scientists have got used to using R\"unbuffers for instrument control. A R\"unbuffer is an array of SICS commands which typically represent a measurement. This R\"unbuffer can be edited at run time. This is very similar to a macro. In contrast to a macro only SICS commands are allowed in R\"unbuffers. When done with  editing the R\"unbuffer it can be entered in a R\"unlist. This is a stack of R\"unbuffers which get executed one by one. While this is happening it is possible (from another client) to  modify the R\"unlist and edit and add additional  R\"unbuffer on top of the stack. This allows for almost infinite measurement and gives more control than a static batch file. In order to cater for this scheme three commands have been defined:

 The {\bf  Buf } object is responsible for creating and deleting  R\"unbuffers. The syntax is:
\begin{itemize}
\item  {\bf  Buf new name } creates a new empty R\"unbuffer with the name name. name will be installed as a SICS object afterwards.
\item  {\bf  Buf copy name1 name2 } copies R\"unbuffer name1 to  buffer name2.
\item  {\bf  Buf del name } deletes the R\"unbuffer name.
\end{itemize}

 After creation, the R\"unbuffer is accessible by his name.  It than understands the commands:
\begin{itemize}
\item  {\bf  NAME append what shall we do with a drunken sailor } will  add all text after append as a new line at the end of the R\"unbuffer.
\item  {\bf  NAME print } will list the contents of the R\"unbuffer.
\item  {\bf  NAME del iLine } will delete line number iLine from the R\"unbuffer.
\item  {\bf  NAME ins iLine BimBamBim } inserts a new line {\bf  after } line iLine into the R\"unbuffer. The line will consist of  everything given after the iLine.
\item  {\bf  NAME subst pattern newval } replaces all occurences of pattern in the R\"unbuffer by the text specified as newval.  Currently this feature allows only exact match but may be expanded to Unix style regexp or shell like globbing.
\item  {\bf  NAME save filename } saves the contents of the R\"unbuffer into file filename.
\item  {\bf  NAME load filename } loads the R\"unbuffer with the data in file filename.
\item  {\bf  NAME run } executes the R\"unbuffer.
\end{itemize}

 The R\"unlist is accessible as object {\bf  stack }. Only one R\"unlist per server is permitted. The syntax:
\begin{itemize}
\item  {\bf  stack add name } adds R\"unbuffer name to the top of the stack.
\item  {\bf  stack list } lists the current R\"unlist.
\item  {\bf  stack del iLine } deletes the R\"unbuffer iLine from  the R\"unlist.
\item  {\bf  stack ins iLine name  } inserts R\"unbuffer name after  R\"unbuffer number iLine into the R\"unlist.
\item  {\bf  stack run } executes the R\"unlist and returns when  all R\"unbuffers are done.
\item  {\bf  stack batch } executes the R\"unlist but does not  return when done but waits for further R\"unbuffers to be added to the list. This feature allows a sort of background process in  the server.
\end{itemize}

% html: End of file: `buffer.htm'
% html: Beginning of file: `drive.htm'

\section{Drive commands}

\label{f9}

 Many objects in SICS are {\bf  drivable }. This means they can run to  a new value. Obvious examples are motors. Less obvious examples include composite adjustments such as setting a wavelength or an energy.  This class of objects can be operated by the  {\bf  drive, run, Success } family of commands. These commands cater  for blocking and non-blocking modes of operation.

 {\bf  run var newval var newval ... } can be called with one to n  pairs of object new value pairs. This command will set the variables in motion and return to the command prompt without waiting for the  requested operations to finish. This feature allows to do things to the instrument while perhaps a slow device is running into position.

 {\bf  Success } waits and blocks the command connection  until all  pending operations have finished (or an interrupt occured). 

 {\bf  drive  var newval var newval ... } can be called with one to n  pairs of object new value pairs. This command will set the variables in motion and wait until the driving has finished. A drive can be  seen as a sequence of a run command as stated above immediatetly  followed by a Success command.
% html: End of file: `drive.htm'
% html: Beginning of file: `logbook.htm'

\section{LogBook command}

\label{f10}

Some users wish like to have all the input typed to SICS and all responses
collected in a file for further review. This is implemented via the LogBook
command. LogBook understands the following syntax:
\begin{description}
\item[ LogBook]  alone prints the name of the current logfile and the status of event
logging.
\item[ LogBook file filename]  This command sets the filename to which output will be printed. 
Please note that this new filename will only be in effect after restarting
logging.
\item[ LogBook on]  This command turns loggin  on. All commands and all answers will be
written to the file defined with the command described above. Please note,
that this command will overwrite an existing file with the same name.
\item[ LogBook off]  This command closes the logfile and ends logging.
\end{description}

% html: End of file: `logbook.htm'
% html: Beginning of file: `commandlog.htm'

\section{The Commandlog}

\label{f11}

The commandlog is a file where all communication with clients
having user or manager privilege is logged. This log allows to retrace each
step of an experiment. This log is usually switched off and must be
configured by the instrument manager. There exists a special command,
commandlog, which allows to control this log file.  
\begin{description}
\item[commandlog new filename] starts a new commandlog writing to filename. Any prior files will be
closed. The log file can be found
in the directory specified by the ServerOption LogFileDir. Usually this is
the log directory.
\item[commandlog] displays the status of the commandlog.
\item[commandlog close] closes the commandlog file.
\item[commandlog auto] Switches automatic log file creation on. This is normally switched on.
Log files are written to the log directory of the instrument account. There
 are time stamps any hour in that file and there is a new file any 24 hours. 
\end{description}

% html: End of file: `commandlog.htm'
% html: Beginning of file: `optimise.htm'

\chapter{The Peak Optimiser}

\label{f12}

In instrument control the need arises to optimise a peak with respect to
several variables. Optimising means finding the maximum of the peak with
respect to several variables.
 This is usefull during instrument calibration.
Four circle diffractometers use this facility on a day to day basis
for finding and verifying the exact position of reflections. In order to
support both usages a more general module has been implemented. The way of
operation is like this:
\begin{verbatim} 
while errors gt precision and cycles lt maxcycles
  for all variables 
      do a scan
      Try find the maximum, two halfwidth points and the peak center.
      if failure extend the scan.
      if success shift the variable, remember last shift. 
      If shift lt precicison mark this variable as done
   end for
end while
\end{verbatim}
Possible outcomes of this procedure are: success, the peak was lost or the
maximum number of cycles was reached. This routine requires that the
instrument is currently placed somewhere on the peak and not miles away.

The Peak Optimiser is implemented as an object with the name opti. It
understand the following commands:
\begin{description}
\item[opti clear]  clears the optimiser.
\item[opti addvar name step nStep precision] This command adds a variable to optimise to the optimiser. The user has
to specify the name of the variable, the step width to use for scanning, the
number of steps needed to cover the full peak when scanning and the
precision which should be achieved when optimising the peak. The step width
and number of steps parameters should cover the whole peak. However, the
Optimiser will extend the scan is the specified range is not sufficient.
\item[opti run] Starts the optimiser. It will then optimise the peak. This may take some
time. 
\end{description}
 The behaviour of the optimiser can be configured by modifying some
parameters. The synatx is easy: {\bf opti parameter} prints the value of the
parameter, {\bf opti parameter newval} sets a new value for the parameter.
The following parameters are supported:
\begin{description}
\item[maxcycles] The maximum number of cycles the optimiser will run when trying to
optimise a peak. The default is 7.
\item[threshold] When a peak cannot be identified after a scan on a variable, the
optimiser will check if there is a peak at all. In order to do that it
searches for a count rate higher then the threshold parameter. If such a
rate cannot be found the optimiser will abort and complain that he lost the
peak.
\item[channel] The counter channel to use for scanning. The default is to use the
counter. By modifying this parameter, the optimiser can optimise on a
monitor instead.
\item[countmode] The counting mode to use when scanning. Possible values are {\bf timer} or
{\bf monitor}. 
\item[preset] The preset value to use for counting in the scan. Depending on the
status of the countmode  parameter this is either a preset time or a preset
monitor.
\end{description}

% html: End of file: `optimise.htm'
% html: Beginning of file: `token.htm'

\section{The Token Command}

\label{f5}

In SICS any client can issue commands to the SICS server. This
is a potential cause for trouble with users issuing conflicting
commands without knowing. In order to deal with this problem a
token mechanism has been developed. A connection can grab a
token and then has full control over the SICS server. Any other
connection will not be privileged to do anything useful, except
looking at things. A token can be released manully with a
special command or is automatically released when the connection
dies. Another command exists which allows a SICS manager to
force his way into the SICS server. The commands in more detail:
\begin{description}
\item[token grab]  Reserves control over the instrument to the client isssuing this
command. Any other client cannot control the instrument now. However, other
clients are still able to inspect variables.
\item[token release]  Releases the control token. Now any other client can control the
instrument  again. Or grab the control token.
\item[token force password] This command forces an existing grab on a token to be released. This
command requires manager privilege. Furthermore a special password must be
specified as third parameter in order to do this. This command does not grab
control though.
\end{description}

% html: End of file: `token.htm'
% html: Beginning of file: `dmchw.htm'

\chapter{DMC Hardware Devices}

\label{f13}
 

DMC controls a couple of :
\begin{itemize}
\item motors (cf.\ Section~\ref{f14}).
\item  a histogram memory (cf.\ Section~\ref{f15}).
\item  a 
counter box (cf.\ Section~\ref{f16}) for
reading monitors.
\item  and various
environment.htm (cf.\ Section~\ref{f17}) control devices. 
\end{itemize}
Each of these
devices understands commands. The syntax understood by each of these devices
will be discussed.


% html: End of file: `dmchw.htm'
% html: Beginning of file: `motor.htm'

\section{SICS motor handling}

\label{f14}
 

 In SICS each motor is an object with a name. Motors may take commands which basically come in the form {\em  motorname command }. Most of these commands deal with the plethora of parameters which are  associated with each motor. The syntax for manipulating variables  is, again, simple. {\em  Motorname parametername } will print the current value of the variable. {\em  Motorname parametername newval } will set the parameter to the new value specified. A list of all  parameters and their meanings is given below. The general principle behind this is that the actual (hardware) motor is kept as stupid  as possible and all the intracacies of motor control are dealt with  in software. Besides the parameter commands any motor understands these basic commands:
\begin{itemize}
\item  {\bf  Motorname list } gives a listing of all motor parameters.
\item  {\bf  Motorname  reset } resets the motor parameters to default  values.
 This is software zero to 0.0 and software limits are reset to hardware 
limits. 
\item  {\bf  Motorname position} prints the current position of the motor.
\item {\bf  Motorname interest} initiates automatic printing of any position
change of the motor. This command is mainly interesting for implementors of
status display clients.
\end{itemize}
 Please note that the actual driving of the motor is done via the  drive (cf.\ Section~\ref{f9}) command.
 

\subsection{The motor parameters}


\begin{itemize}
\item  {\bf  HardLowerLim } is the hardware lower limit. This is read  from the motor controller and is identical to the limit switch welded  to the instrument. Can usually not be changed.
\item  {\bf  HardUpperLim } is the hardware upper limit. This is read  from the motor controller and is identical to the limit switch welded  to the instrument. Can usually not be changed.
\item  {\bf  SoftLowerLim } is the software lower limit. This can be  defined by the user in order to restrict instrument movement in special  cases.
\item  {\bf  SoftUpperLim } is the software upper limit. This can be  defined by the user in order to restrict instrument movement in special  cases.
\item  {\bf  SoftZero } defines a software zero point for the motor.  All further movements will be in respect to this zeropoint.
\item  {\bf  Fixed } can be greater 0 for the motor being fixed and less 
or equal  than zero for the motor being movable.
\item  {\bf  InterruptMode } defines the interrupt to issue when the motor  fails. Some motors are so critical for the operation of the instrument  that all operations shall be stopped when there is a problem. Other are  less critical. This criticallity is expressed in terms of interrupts,  denoted by integers in the range 0 - 4 translating into the interrupts:  continue,  AbortOperation, AbortScan,  AbortBatch and Halt. This  parameter can usually only be set by managers.
\item  {\bf  Precision } denotes the precision to expect from the motor  in positioning. Can usually only be set by managers.
\item  {\bf  AccessCode } specifies the level of user privilege  necessary to  operate the motor. Some  motors are for  adjustment only and can be harmful to move once the  adjustment has been done. Others must be moved for the experiment. Values  are 0 - 3 for internal, manager, user and spy. This parameter can  only be changed by managers.
\item  {\bf  Speed }, defunct.
\item  {\bf  Sign } allows to reverse the operating sense of the motor.  For cases where electricians and not physicists have defined the  operating sense of the motor. Usually a parameter not to be changed  by ordinary users.
\end{itemize}


% html: End of file: `motor.htm'
% html: Beginning of file: `histogram.htm'

\section{Histogram memory}

\label{f15}
 

Histogram memories are used in order to control large area sensitive
detectors or single detectors with time binning information. 
Basically each detector maps to a defined memory location. The
histogram memory wizard takes care of putting counts detected in the
detector into the proper bin in memory. Some instruments resolve energy
(neutron flight time) as
well, than there is for each detector a row of memory locations mapping to
the time bins. As usual in SICS the syntax is the name of the histogram
memory followed by qualifiers and parameters. As a placeholder for the
histogram memories name in your system, HM will be used in the following
text.

A word or two has to be lost about the SICS handling of preset values for 
histogram memories.
 Two modes of operation have to be distinguished: counting until a timer has passed,
for example: count for 20 seconds. This mode is called timer mode. In the other
mode, counting is continued until a control monitor has reached a certain 
preset value. This mode is called Monitor mode. The preset values in Monitor
mode are usually very large. Therefore the counter has an exponent data variable.
Values given as preset are effectively 10 to the power of this exponent. For 
instance if the preset is 25 and the exponent is 6, then counting will be
continued until the monitor has reached 25 million. Note, that this scheme with 
the exponent is only in operation in Monitor mode.

\subsection{ Configuration}



A HM has a plethora of configuration options coming with it which define
memory layout, modes of operation, handling of bin overflow and the like.
Additionally there are HM model specific parameters which are needed
internally in
order to communicate with the HM. In
most cases the HM will already have been configured at SICS server startup
time. However, there are occasion where these configuartion option need to
enquired or modified at run time. The command to enquire the current value
of a configuration option is: {\bf HM configure option}, the command to set it is:
{\bf  HM configure option newvalue}. A list of common configuration options and their
meaning is given below:
\begin{description}
\item[ HistMode]  HistMode describes the modes of operation of the histogram memory.
Possible values are:
\begin{itemize}
\item Transparent, Counter data will be written as is to memory. For debugging
purposes only.
\item  Normal, neutrons detected at a given detector will be added to the
 apropriate memory bin.
\item  TOF, time of flight mode, neutrons found in a given detector will be
put added to a memory location determined by the detector and the time
stamp.
\item  Stroboscopic mode. This mode serves to analyse changes in a sample due
to an varying external force, such as a magnetic field, mechanical stress
or the like. Neutrons will be stored in memory according to detector
position and phase of the external force.
\end{itemize}
\item[ OverFlowMode]  This parameter determines how bin overflow is handled. This happend
when more neutrons get detected for a particular memory location then are
allowed for the number type of the histogram memory bin. Possible values
are:
\begin{itemize}
\item Ignore. Overflow will be ignored, the memory location will wrap around
and start at 0 again.
\item Ceil. The memory location will be kept at the highest posssible value
for its number type.
\item Count. As Ceil, but a list of overflowed bins will be maintained.
\end{itemize}
\item[ Rank]  Rank defines the number of histograms in memory.
\item[ Length ]  gives the length of an individual histogram.
\item[ BinWidth]  determines the size of a single bin in histogram memory in bytes.
\item[dim0, dim1, dim2, ... dimn] define the logical dimensions of the histogram. Must be set if the 
 the sum command (see below) is to be used. This is a clutch necessary to 
 cope with the different notions of dimensions in the SINQ histogram memory 
 and physics.
\end{description}
For time of flight mode the time binnings can be retrieved and modified with
the following commands. Note that these commands do not follow the configure
syntax given above. Please note, that the usage of the commands for
modifying time bins is restricted to instrument managers.
\begin{description}
\item[HM timebin]  Prints the currently active time binning array.
\item[HM genbin start step n] Generates a new equally spaced time binning array. Number n time bins
will be generated starting from start with a stepwidth of step.
\item[HM setbin inum value] Sometimes unequally spaced time binnings are needed. These can be
configured with this command. The time bin iNum is set to the value value.
\item[HM clearbin] Deletes the currently active time binning information. 
\end{description}
 
\subsection{Histogram Memory  Commands}



Besides the configuration commands the HM understands the following
commands:
\begin{description}
\item[HM preset]  with a new value sets the preset time or monitor for counting. Without a
value prints the current value.
\item[HM exponent]  with a new value sets the exponent to use for the preset time 
in Monitor mode. Without a
value prints the current value.
\item[CountMode ]  with a new values sets the count mode. Possible values are Timer for a
fixed counting time and Monitor for a fixed monitor count which has to be
reached before counting finishes. Without a value print the currently active
value.
\item[HM init ]  after giving configuration command sthis needs to be called in order to
transfer the configuration from the host computer to the actual HM.
\item[HM count]  starts counting using the currently active values for CountMode and
preset. This command does not block, i.e. in order to inhibit further
commands from the console, you have to give Success afterwards.
\item[HM InitVal val]  initialises the whole histogram memory to the value val. Ususally 0 in
order to clear the HM. 
\item[ HM get i iStart iEnd]  retrieves the histogram number i. A value of -1 for i denotes retrieval
of the whole HM. iStart and iEnd are optional amd
allow to retrieve a subset of a histogram between iStart and iEnd.   
\item[HM sum d1min d1max d2min d2max .... dnmin dnmax] calculates the sum of an area on the detector. For each dimension a 
 minimum and maximum boundary for summing must be given. 
\end{description}

% html: End of file: `histogram.htm'
% html: Beginning of file: `counter.htm'

\section{SICS counter handling}

\label{f16}
 

 This section deals with the SICS interface to single counters.  
Where the SICS counter concept may include several monitors per  
counter. A counter is, again, a named object which takes commands. 
A word or two has to be lost about the SICS handling of preset values for counters. 
Two modes of operation have to be distinguished: counting until a timer has passed,
for example: count for 20 seconds. This mode is called timer mode. In the other
mode, counting is continued until a control monitor has reached a certain 
preset value. This mode is called Monitor mode. The preset values in Monitor
mode are usually very large. Therefore the counter has an exponent data variable.
Values given as preset are effectively 10 to the power of this exponent. For 
instance if the preset is 25 and the exponent is 6, then counting will be
continued until the monitor has reached 25 million. Note, that this scheme with 
the exponent is only in operation in Monitor mode.
 The commands understood are:
\begin{itemize}
\item   {\bf  countername SetPreset val } sets the counting preset to  val.
\item   {\bf  countername GetPreset } prints the current preset value.
\item   {\bf  countername SetExponent val } sets the exponent for the counting 
preset in monitor mode to  val.
\item   {\bf  countername GetExponent } prints the current exponent used 
in monitor mode.
\item   {\bf  countername SetMode val } sets the counting mode to  val. Possible values are Timer for timer mode operation and Monitor  for waiting for a monitor to reach a certain value.
\item   {\bf  countername GetMode } prints the current mode.
\item  {\bf  countername GetCounts } prints the counts gathered in the  last run.
\item  {\bf  countername GetMonitor n } prints the counts gathered in the  monitor number n in the last run.
\item  {\bf  countername Count preset } starts counting in the current mode and the the preset preset.
\item  {\bf  countername status } prints a message containing the preset and
the current monitor or time value. Can be used to monitor the progress of
the counting operation.
\item  {\bf  countername gettime } Retrieves the actual time the counter
counted for. This excludes time where there was no beam or counting was
paused.
\item {\bf countername getthreshold m} retrieves the value of the threshold 
 set for the monitor number m. 
\item {\bf countername setthreshold  m val} sets the threshold for monitor m
 to val. WARNING: this also makes monitor m the active monitor for evaluating
 the threshold. Though the EL7373 counterbox does not allow to select the 
 monitor to use as control monitor in monitor mode, it allows to choose 
 the monitor used for pausing the count when the count rate is below the
 threshold (Who on earth designed this?)  
\end{itemize}

% html: End of file: `counter.htm'
% html: Beginning of file: `samenv.htm'

\chapter{ Sample Environment Devices}

\label{f17}


\section{SICS Concepts for Sample Environment Devices}

\label{f17:concept}

SICS can support any type of sample environment control device if there is a 
driver for it. This includes temperature controllers, magnetic field controllers  
etc. The SICS server is meant to be left running continously. Therefore there
exists a facility for dynamically configuring and deconfiguring environment
devices into the system. This is done via the {\bf EVFactory} command.
It is expected that instrument scientists will provide command procedures or
specialised R\"unbuffers for configuring environment devices and setting
reasonable default parameters. 

 In the SICS model
a sample environment device has in principle two modes of operation. The first
is the drive modus. The device is monitored in this modus when a new value for it
has been requested. The second modus is the monitor modus. This modus is entered
when the device has reached its target value. After that, the device must be
continously monitored throughout any measurement. This is done through the 
environment monitor or {\bf emon}. The emon understands a few commands of its 
own.  

Within SICS all sample environement devices share some common behaviour
concerning parameters and abilities. Thus any given environment device 
accepts all of a set of general commands plus some additional commands 
special to the device. 

In the next section the EVFactory, emon and the general commands understood
by any sample environment device will be discussed. This reading is mandatory
for understanding SICS environment device handling. Then there will be another
section discussing the special devices known to the system.


\section{SampleEnvironment Error Handling}


A  \label{f17:error}sample environment device may fail to  stay at its preset value during a 
measurement. This condition will usually be detected by the emon. The question 
is how to deal with this problem. The requirements for this kind of error
handling are quite differntiated. The SICS model therefore implements several
strategies for handling  sample environment device failure handling.
The strategy to use is selected via variable which can be set by the user for
any sample environment device separatetly. Additional error handling strategies 
can be added with a modest amount of programming.  The error handling strategies currently 
implemented are:
\begin{description}
\item[Lazy] Just print a warning and continue.
\item[Pause] Pauses the measurement until the problem has been resolved.
\item[Interrupt] Issues a SICS interrupt to the system.
\item[Safe]  Tries to run the environment device to a value considered safe by the
user.
\end{description}

\section{General Sample Environment  Commands}

\label{f17:general}

\subsection{EVFactory}



EVFactory is responsible for configuring and deconfiguring  sample environment
devices into SICS. The syntax is simple:
\begin{description}
\item[EVFactory new name type par par ...] Creates a new sample environment device. It will be known to SICS by the 
name specified as second parameter. The type parameter decides which driver to
use for this device. The type will be followed by additional parameters 
which will be evaluated by the driver requested.
\item[EVFactory del name] Deletes the environment device name from the system.
\end{description}

\subsection{emon}



The environment monitor emon takes for the monitoring of an environment device
during measurements. It also initiates error handling when appropriate. The emon
understands a couple of commands.
\begin{description}
\item[emon list] This command lists all environment devices currently registered in the
system.
\item[emon register name]  This is a specialist command which registers the environment device name 
with the environment monitor. Usually this will automatically be taken care
of by EVFactory.
\item[emon unregister name]  This is a specialist command which unregisters the environment device name 
with the environment monitor. Usually this will automatically be taken care
of by EVFactory Following this call the device will no longer be monitored and
out of tolerance errors on that device no longer be handled.
\end{description}

\subsection{General
 Commands UnderStood by All Sample Environment  Devices}

\label{f17:all}

Please note that each command discussed below MUST be prepended with the name
of the environment device as configured in EVFavtory!

The general commands understood by any environment controller can be subdivided
further into parameter commands and real commands. The parameter commands just
print the name of the parameter if given without an extra parameter or 
set if a parameter is specified. For example:
\begin{quotation} 
Temperature Tolerance\end{quotation}
prints the value of the variable Tolerance for the environment controller
Temperature.
\begin{quotation} 
Temperature Tolerance 2.0\end{quotation}
sets the parameter Tolerance for Temperature to 2.0. Parameters known to ANY
envrironment controller are:
\begin{description}
\item[Tolerance] Is the deviation from the preset value which can be tolerated before an
error is issued.
\item[ Access] Determines who may change parameters for this controller. 
Possible values are:
\begin{itemize}
\item 0 only internal
\item  1 only Managers 
\item  2 Managers and Users.
\item  3 Everybody, including Spy.
\end{itemize}
\item[LowerLimit]  The lower limit for the controller.
\item[UpperLimit]  The upper limit for the controller.
\item[ErrHandler.]  The error handler to use for this controller. Possible values:
\begin{itemize}
\item 0 is Lazy.
\item 1  for Pause.
\item  2 for Interrupt
\item  3 for Safe.
\end{itemize}
 For an explanantion of these values see the section about error (cf.\ Section~\ref{f17:error}) handling
above.
\item[ Interrupt]  The interrupt to issue when an error is detected and Interrupt error 
handling is set. Valid values are:
\begin{itemize}
\item  0 for Continue.
\item  1 for abort operation.
\item  2 for abort scan.
\item  3 for abort batch processing.
\item  4 halt system.
\item  5 exit server. 
\end{itemize}
\item[SafeValue]  The value to drive the controller to when an error has been detected and 
Safe error handling is set.
\end{description}

Additionally the following commands are understood:
\begin{description}
\item[send par par ...] Sends everything after send directly to the controller and return its 
response. This is a general purpose command which allows to manipulate controllers
and controller parameters directly. The protocoll for these commands is
 documented in the documentation for each controller. Ordinary users should
not tamper with this. This facility is meant for setting up the device with
calibrartion tables etc.
\item[ list]  lists all the parameters for this controller.
\item[ no command, only name.]  When only the name of the device is typed it will return its
current value.
\item[ name val ]  will drive the device to the new value val. Please note that the same
can be achieved by using the drive command. 
\item[ name log on]  Switches logging on. If logging is on, at each cycle in the emon the 
current value of the environment variable will be recorded together with a 
time stamp. Be careful about this, for each log point a bit of memory is
allocated. At some time the memory is exhausted! Log clear frees it again
and log frequency (both below) allows to set the logging time intervall.  
\item[ name log off] Switches logging off.
\item[name log clear]  Clears all recorded  time stamps and values.
\item[name log gettime] This command retrieves a list of all recorded time stamps.
\item[name log getval]  This command retrieves all recorded values.
\item[name log getmean] Calculates the mean value and the standard deviation for all logged
values and prints it. 
\item[name log frequency val]  With a parameter sets, without a parameter requests the logging intervall 
for the log created. This parameter specifies the time intervall in seconds
 between log records. The default is 5 minutes. A value of 0 means a record any
 cycle of the SICServer.
  \end{description}

\section{Special Environment Control Devices}



This section lists the parameters needed for configuring a special environment
device into the system and special parameters and commands only understood by
that special device. All of the general commands listed above work as well! 

\subsection{ITC-4 and ITC-503 Temperature Controllers}

\label{f17:itc4}

These temperature controller are fairly popular at SINQ. It is manufactured by
Oxford Instruments. At the back side of this controller there is a RS-232
socket which must be connected to a Macintosh computer running the SINQ 
terminal server program via a serial cable. Please make sure with a different
Macintosh or a PC that the serial line is OK and the ITC-4 responding before
plugging it in.

\subsubsection{ITC-4 Initialisation}



An ITC-4 can be configured into the system by:
\begin{quotation} 
EVFactory new Temp ITC4 computer port channel\end{quotation}
This creates an ITC-4 controller object named Temp within the system. The
ITC-4 is expected to be connected to the serial port channel at the 
Macintosh computer computer running the SINQ terminal server program 
listening at port port. For example:
\begin{quotation} 
EVFactory new Temp ITC4 lnsp22.psi.ch 4000 6\end{quotation}
connects Temp to the Macintosh named lnsp22, serial port 5 (6 above is no typo!), 
 listening at port 4000.

\subsubsection{ITC-4 Additional Parameters}



The ITC-4 has a few more parameter commands:
\begin{description}
\item[timeout] Is the timeout for the Macintosh terminal server program waiting for
responses from the ITC-4. Increase this parameter if error messages
containg ?TMO creeping up. 
\item[ sensor]  Sets the sensor number to be used for reading temperature.
\item[ control]  Sets the control sensor for the ITC-4. This sensor will be used 
internally for regulating the ITC-4.
\item[divisor] The ITC4 does not understand floating point numbers, the ITC-503 does. 
In order to make ITC4's read and write temperatures correctly floating point
values must be multiplied or divided with a magnitude of 10. This parameter
determines the appropriate value for the sensor. Is usually 10 for a sensor
with one value behind the comma or 100 for a sensor with two values after
the comma.
\item[multiplicator] The same meaning as the divisor above, but for the control sensor.   
\end{description}

\subsubsection{Installing an ITC4 step by step}



\begin{enumerate}\item Connect the ITC temperature controller to port 6 on the Macintosh 
serial port extension box. Port 6 is specially configured for dealing with
the ideosyncracies of that device. No null modem is needed.
\item Install the ITC4 into SICS with the command: \newline
evfactory new name Macintoshname 4000 7\newline
Thereby replace name with the name you want to address the ITC4 in SICS. A
good choice for a name  is temperature, as such a value will be written to data files.
Please note, that SICS won't let you use that name if it already exists. For
instance if you already had a controller in there. Then the command:\newline
evfactory del name \newline
will help. Macintoshname is the name of the instrument Macintosh PC.
\item Configure the upper and lowerlimits for your controller appropriatetly.
\item Figure out which sensor you are going to use for reading temperatures.
Configure the sensor and the divisor parameter accordingly.
\item Figure out, which sensor will be used for controlling the ITC4. Set the
parameters control and multiplicator accordingly. Can be the same as the
sensor.
\item Think up an agreeable temperature tolerance for your measurement. This
tolerance value will be used 1) to figure out when the ITC4 has reached its
target position. 2) when the ITC4 will throw an error if the ITC4 fails to
keep within that tolerance. Set the tolerance parameter according to the
results of your thinking.
\item Select one of the numerous error handling strategies the control
software is able to perform. Configure the device accordingly.
\item  Test your setting by trying to read  the current temperature. 
\item  If this goes well try to drive to a temperature not to far from the
current one.
\end{enumerate}

\subsubsection{ITC-4 Trouble Shooting}



If the ITC-4 {\bf does not respond at all}, make sure the serial connection to
the Macintosh is working. Use standard RS-232 debugging procedures for doing
this. The not responding may also come up as a failure to connect to the ITC-4
during startup.

 If error messages containing the string {\bf ?TMO} keep creeping up followed
by all signs of command not understood, then increase the timeout. The standard
timeout of 10 microseconds is to short at times.

You keep on reading {\bf wrong values} from the ITC4. Mostly off by a
factor 10. Then set the divisor correctly. Or you may need to choose a
decent sensor for that readout.

Error messages when {\bf trying to drive the ITC4}. These are usually the
result of a badly set multiplicator parameter for the control sensor. 

The ITC4 {\bf never stops driving}. There are at least four possible
causes for this problem: 
\begin{enumerate}
\item The multiplicator for the control sensor was wrong and the ITC4 has now
a set value which is different from your wishes. You should have got error
messages then as you tried to start the ITC4.
\item The software is reading back wrong temperature  because the sensor and 
divisor parameters are badly configured. Try to read the temperature and if
it does have nothing to do with reality, set parameters accordingly. 
\item The tolerance parameter is configured so low, that the ITC4 never
manages to stay in that range. Can also be caused by inappropriate PID
parameters in the ITC4. 
\item 
You are reading on one sensor (may be 3) and controlling on another one (may
be 2). Then it may happen that the ITC 4 happily thinks that he has reached
the temperature because its control sensor shows the value you entered as
set value. But read sensor 3 still thinks he is far off. The solution is to
drive to a set value which is low enough to make  the read sensor think it is 
within the tolerance. That is the temperature value you wanted after all.    
\end{enumerate}

\subsection{Haake Waterbath Thermostat}

\label{f17:haake}

This is sort of a buck full of water equipped with a temperature 
control system. The RS-232 interface of this device can only be operated at
4800 baud max. This is why it has to be connected to the serial printer port
of the Macintosh serial port server computer. This makes the channel number to
use for initialisation a 1 always. The driver for this device has been
realised in the Tcl extension language of the SICS server. A prerequisite
for the usage of this device is that the file hakle.tcl is sourced in the
SICS initialisation file and the command inihaakearray has been published.
 Installing the
Haake into SICS requires two steps: first create an array with
initialisation parameters, second install the device with evfactory. A
command procedure is supplied for the first step. Thus the initialisation
sequence becomes:
\begin{quotation} 
inihaakearray name-o-array macintosh-computer name port channel\newline
evfactory new temperature tcl name-of-array\end{quotation}
An example for the SANS:
\begin{quotation} 
inihaakearray eimer lnsp25.psi.ch 4000 1 \newline
evfactory new temperature tcl eimer\end{quotation}
Following this, the thermostat can be controlled with the other environment
control commands.

The Haake Thermostat understands a single special subcommand: {\bf sensor}.
The thermostat may be equipped with an external sensor for controlling and
reading. The subcommand sensor allows to switch between the  two. The exact
syntax is:
\begin{quotation} 
temperature sensor val\end{quotation}
val can be either intern or extern. 

\subsection{Dilution Cryostat}

\label{f17:dilu}

This is a large ancient device for reaching very low temperatures. This
cryostat can be configured into SICS with the command:
\begin{verbatim} 
EVFactory new Temp dillu computer port channel table.file
\end{verbatim}
Temp is the name of the dilution controller command in SICS, dillu is the
keyword which selects the dilution driver, computer, port and channel are
the parameters of the Macintosh-PC running the serial port server program. 
table.file is the fully qualified name of a file containing a translation
table  for this cryostat. The readout from the dilution controller is a
resistance. This table allows to interpolate the temperature from the
resistance measurements and back. Example:
\begin{verbatim} 
evfactory new temperature dillu lnsp19.psi.ch 4000 1 dilu.tem
\end{verbatim}
installs a new dilution controller into SICS. This controller is connected
to port 1 at the Macintos-PC with the newtwork adress lnsp19.psi.ch. On this
macintosh-PC runs a serial port server program listening at TCP/IP port
4000. The name of the translation table file is dilu.tem.

The dilution controller has no special commands, but two caveats: As of
current (October 1998) setting temperatures does not work due to problems
with the electronics. Second the dilution controller MUST be connected to
port 1 as only this port supports the 4800 maximum baud rate this device
digests.

\subsection{Bruker Magnet Controller B-EC-1}

\label{f17:bruker}

This is the Controller for the large magnet at SANS. The controller is a
box the size of a chest of drawers. This controller can be operated in one
out of two modes: in {\bf field} mode the current for the magnet is controlled via
an external hall sensor at the magnet. In {\bf current} mode, the output current
of the device is controlled. This magnet can be configured into SICS with a
command syntax like this:  
\begin{quotation} 
evfactory new name bruker Mac-PC Mac-port Mac-channel\end{quotation}

name is a placeholder for the name of the device within SICS. A good
suggestion (which will be used throughout the rest of the text) is magnet.
bruker is the keyword for selecting the bruker driver. Mac-PC is the name of
the Macintosh PC to which the controller has been connected, Mac-Port is the
port number at which the Macintosh-PC's serial port server listens.
Mac-channel is the RS-232 channel to which the controller has been
connected. For example (at SANS):
\begin{verbatim} 
evfactory new magnet bruker lnsp25.psi.ch 4000 9
\end{verbatim}

creates a new command magnet for a Bruker magnet Controller connected to
serial port 9 at lnsp25.
In addition to the standard environment controller commands this magnet
controller understands the following special commands:
\begin{description}
\item[magnet polarity]  Prints the current polarity setting of the controller. Possible
answers are plus, minus and busy. The latter indicates that the controller
is in the process of switching polarity after a command had been given to
switch it.
\item[magnet polarity val] sets a new polarity for the controller. Possible values for val are
{\bf minus} or {\bf plus}. The meaning is self explaining.
\item[magnet mode]  Prints the current control mode of the controller. Possible
answers are {\bf field} for control via hall sensor or {\bf current} for
current control. 
\item[magnet mode val] sets a new control mode for the controller. Possible values for val are
{\bf field} or {\bf current}. The meaning is explained above.
\item[magnet field] reads the magnets hall sensor independent of the control mode.
\item[magnet current] reads the magnets output current  independent of the control mode.
\end{description}

Warning: There is a gotcha with this. If you type only magnet a
value will be returned. The meaning of this value is dependent on the
selected control mode. In current mode it is a current, in field mode it is
a magnetic field. This is so in order to support SICS  control logic. 
You can read values at all times explicitly using magnet current or 
magnet field.

\subsection{The CryoFurnace.}

\label{f17:ltc11}

The CryoFurnace at PSI is equipped with a Neocera LTC-11 temperature
controller. This controller can control either an heater or an analag output
channel. Futhermore a choice of sensors can be selected for controlling the
device. The LTC-11 behaves like a normal SICS environment control device
plus a few additional commands. An LTC-11 can be configured into SICS with
the following command:
\begin{quotation} 
evfactory new name ltc11 Mac-PC Mac-port Mac-channel\end{quotation}

name is a placeholder for the name of the device within SICS. A good
suggestion is temperature.
ltc11 is the keyword for selecting the LTC-11 driver. Mac-PC is the name of
the Macintosh PC to which the controller has been connected, Mac-Port is the
port number at which the Macintosh-PC's serial port server listens.
Mac-channel is the RS-232 channel to which the controller has been
connected. For example (at DMC):
\begin{verbatim} 
evfactory new temperature ltc11 lnsp18.psi.ch 4000 6
\end{verbatim}

creates a new command magnet for a LTC-11 temperature Controller connected to
serial port 6 at lnsp18.

The additional commands understood by the LTC-11 controller are:
\begin{description}
\item[temperature sensor ]  allows to query the current sensor used for temperature readout.
\item[temperature sensor val ]  allows to select the  sensor val for temperature readout.
\item[temperature controlanalog ]  allows to query the sensor used for controlling the analog channel.
\item[temperature controlanalog val ]  allows to select the  sensor val for controlling the analog channel.
\item[temperature controlheat ]  allows to query the sensor used for controlling the heater channel.
\item[temperature controlheat val ]  allows to select the  sensor val for controlling the heater channel.
\item[temperature mode] Allows to query if the LTC-11 controls the analog or heater channel.
\end{description}
 
Further notes: As the CryoFurnace is very slow and the display at the
controller becomes unusable when the temperature is read out to often, the
LTC-11 driver buffers the last temperature read for 5 seconds. Setting the
mode of the LTC-11 is possible by computer, but not yet fully understood and
 therefore unusable.

\subsection{The Eurotherm Temperature Controller}

\label{f17:euro}

At SANS there is a Eurotherm temperature controller for the sample heater.
 This and probably other Eurotherm controllers can be configured into SICS
with the following command. The eurotherm needs to be connected with a 
 nullmodem adapter.
\begin{quotation} 
evfactory new name euro Mac-PC Mac-port Mac-channel\end{quotation}

name is a placeholder for the name of the device within SICS. A good
suggestion is temperature.
euro is the keyword for selecting the Eurotherm driver. Mac-PC is the name of
the Macintosh PC to which the controller has been connected, Mac-Port is the
port number at which the Macintosh-PC's serial port server listens.
Mac-channel is the RS-232 channel to which the controller has been
connected. {\bf WARNING:} The eurotherm needs a RS-232 port with an unusual
 configuration: 7bits, even parity, 1 stop bit. Currently only the SANS 
 Macintosh port 13 (the last in the upper serial port connection box) is 
 configured like this! Thus, an example for SANS and the name temperature 
 looks like:
\begin{verbatim} 
evfactory new temperature euro lnsp25.psi.ch 4000 13
\end{verbatim}

There are two further gotchas with this thing:
\begin{itemize}
\item The eurotherm needs to operate in the EI-bisynch protocoll mode. This has 
to be configured manually. For details see the manual coming with the machine.
\item The weird protocoll spoken by the Eurotherm requires very special control
 characters. Therefore the send functionality usually supported by a SICS 
  environment controller could not be implemented. 
\end{itemize}

% html: End of file: `samenv.htm'
% html: Beginning of file: `dmcdev.htm'

\chapter{DMC-specific command and device list}

\label{f18}
 

\section{DMC specific commands}



\begin{description}\item[StoreData] Does what it says. Writes the current state of the instrument 
including counts  to a NeXus data file. 
\item[count mode preset]  Does a count operation in mode with a preset of preset. 
 The parameters are optional. If they are not
 given the count will be started with the current setting in the histogram 
memory object. After the count, StoreData will be automatically called.
\item[ Repeat num mode preset.]  Calls count num times. num is a required parameter. The other two are
 optional and are handled as described above for count.
\item[ scan motor start step n mode preset]  This command allows for scanning a motor against monitors 0 and 1. This
 command may only be used by managers. Its only purpose is to facilitate
 the adjustment of the instrument. In order to obtain a copy of the scan
 results, a user must take great care to enable command logging. The
 parameters are: a motor to be scanned, a start value for the scan, a 
 step width for the scan, the number of scan points, optionally a count 
 mode and a preset value for counting. Both these parameters have meanings
 as described above for the count command.  
\end{description}

\section{DMC motor list}



\begin{description}\item[OmegaM, A1] Omega monochromator.
\item[TwoThetaM, A2]  Two Theta monochromator
\item[MonoX] X-translation table of the monochromator.
\item[MonoY] Y-translation table for the monochromator.
\item[CurveM] Monochromator curvature.
\item[MonoPhi] Phi angle of the monochromator.
\item[MonoChi] Chi angle for the monochromator.
\item[Table, A3] Sample rotation.
\item[TwoThetaD, A4] Two Theta detector.
\end{description}

\section{Other DMC devices}



\begin{description}\item[banana] Histogram memory.
\item[counter]  EL737 counter box.
\end{description}

\section{DMC Variables}



\begin{description}\item[Instrument] Instrument name.
\item[Title] Experiment title.
\item[comment1, comment2, comment3]  comment lines to be stored with the data.
\item[Collimation] Text line describing collimators in use.
\item[User]  User name.
\item[Adress] User adress
\item[phone]  User phone number.
\item[fax]  User fax number
\item[email] User email adress.
\item[Sample]  Sample name
\item[sample\_mur]  Absorption coefficient of sample.
\end{description}

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

\chapter{SICS Trouble Shooting }

\label{f1}
 

There is no such thing as bug free software. There are always bugs, nasty
behaviour etc. This document shall help to solve these problems. The usual
symptom will be that a client cannot connect to the server or the server is
not responding. 

An essential prerequisite of SICS is that the server is up
and running. The system is configured to restart the SICServer whenever it
fails. Only after a reboot or when the keepalive processes were killed (see
below) the SICServer must be restarted. This is done for all instruments by
typing: 
\begin{verbatim} 
startsics 
\end{verbatim}
at the command prompt. startsics actually starts two programs: one is
the replicator application which is responsible for the automatic
copying of data files to the laboratory server. The other is the SICS
server. Both programs are started by means of a shell script called
{\bf keepalive}. keepalive is basically an endless loop which calls
the program again and agaian and thus ensures that the program will
never stop running.   

 When the SICS server hangs, or you want to enforce an reinitiliazation  of 
everything  the server process must be killed. The first thing to
do is to find the process. 

\section{Finding the SICS server}



Log in as  Instrument user on the instrument computer (for instance DMC on
lnsa05). Type the command:
\begin{verbatim} 
/home/DMC> ps -A
\end{verbatim}
Note the capital A given as parameter. The reward will be listing like this:
\begin{verbatim} 
  PID TTY      S           TIME CMD
    0 ??       R       01:56:28 [kernel idle]
    1 ??       I        1:24.44 /sbin/init -a
    3 ??       IW       0:00.20 /sbin/kloadsrv
   24 ??       S       40:39.58 /sbin/update
   97 ??       S        0:04.87 /usr/sbin/syslogd
   99 ??       IW       0:00.03 /usr/sbin/binlogd
  159 ??       S        1:43.70 /usr/sbin/routed -q
  285 ??       S        1:00.45 /usr/sbin/portmap
  293 ??       S        6:03.45 /usr/sbin/ypserv
  299 ??       I        0:00.37 /usr/sbin/ypbind -s -S psunix,lnsa05.psi.ch
  307 ??       I        0:00.52 /usr/sbin/mountd -i
  309 ??       I        0:00.07 /usr/sbin/nfsd -t8 -u8
  311 ??       I        0:00.09 /usr/sbin/nfsiod 7
  317 ??       S        5:51.54 /usr/sbin/automount -f /etc/auto.master -M /psi
  370 ??       I        0:28.58 -accepting connections (sendmail)
  389 ??       S        1:41.15 /usr/sbin/xntpd -g -c /etc/ntp.conf
  419 ??       S        6:00.16 /usr/sbin/snmpd
  422 ??       S        1:00.91 /usr/sbin/os_mibs
  438 ??       S       34:29.67 /usr/sbin/advfsd
  449 ??       I        3:16.29 /usr/sbin/inetd
  482 ??       IW       0:11.53 /usr/sbin/cron
  510 ??       IW       0:00.02 /usr/lbin/lpd
  525 ??       I        5:31.67 /usr/opt/psw/psw_agent -x/dev/null -f/usr/opt/psw/psw_agent.conf
  532 ??       I        0:00.74 /usr/opt/psw/psw_sensor_syswd 1 -x/dev/null
  555 ??       I        0:00.58 /usr/bin/nsrexecd
  571 ??       I        0:20.27 /usr/dt/bin/dtlogin -daemon
  583 ??       S        1:38.27 lpsbootd -F /etc/lpsodb -l 0 -x 1
  585 ??       IW       0:00.04 /usr/sbin/getty /dev/lat/620 console vt100
  586 ??       IW       0:00.03 /usr/sbin/getty /dev/lat/621 console vt100
  587 ??       I       35:59.85 /usr/bin/X11/X :0 -auth /var/dt/authdir/authfiles/A:0-aaarBa
  657 ??       I        0:01.46 rpc.ttdbserverd
 4705 ??       IW       0:00.05 dtlogin   -daemon
 9127 ??       I        0:00.37 /usr/bin/X11/dxconsole -geometry 480x150-0-0 -daemon -nobuttons -verbose -notify -exitOnFail -nostdin -bg gray
 9317 ??       IW       0:00.73 dtgreet -display :0
14412 ??       S        0:39.71 netscape
15524 ??       I        0:00.57 rpc.cmsd
21678 ??       S        0:00.11 telnetd
31912 ??       S        0:10.65 /home/DMC/bin/SICServer /home/DMC/bin/dmc.tcl
  584 console  IW +     0:00.21 /usr/sbin/getty console console vt100
21978 ttyp1    S        0:00.63 -tcsh (tcsh)
22269 ttyp1    R  +     0:00.10 ps -A
\end{verbatim}
This is a listing of all running processes on the machine where this command
has been typed. Note, in this case, at the bottom in the line starting with 
{\tt  31912 ?? } an entry for the SICS server. In this example the server
is running. If the server is down, no such entry would be present. 

\section{ Killing a hanging SICS server }



Suppose, the situation is that the SICS server does not respond anymore. It
needs to be forcefully exited. Please note, that it is always better to
close the server via the {\tt Sics\_Exitus} command typed with manager
privilege in one of the command clients. In order to kill the server it is
needed to find him first using the scheme given above. The information
needed is the number given as first item in the same line where the server
is listed. In this case: {\tt 31912}. Please note, that this number will
always be different. The command to force the server to stop is:
\begin{verbatim} 
/home/DMC> kill -9 31912
\end{verbatim}
Note, the second parameter is the number found with {\tt ps -A}.  The
SICServer will be restarted automatically by the system. Occasionally, it
may happen, that you cannot connect to the SICS server after such an
operation. This is due to some network buffering problems. Doing the killing
again usually solves the problem.

\section{ Shutting the SICS server down completely}



In order to completely shutdown the SICS server two process must be killed:
the actual SICS server and the process which automatically restarts the
SICServer. The latter must be killed first. It can be found in the ps -A
listing as a line reading {\bf keepalive SICServer }. Kill that one as
described above, then kill the SICServer. For restarting SICS after this,
use the startsics command.

\section{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 400 meters.
\begin{enumerate}
\item  Reboot the Macintosh PC by switching it off at the silver button on the
left. Press deep and a few seconds to achieve an effect. The LED right to the
button should be off, before you press again to boot the Macintosh. 
\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  Wait 5 minutes. The Macintosh may take that time to come up again.
\item  Restart the SICServer. Watch for any messages about things not being 
connected or configured.
\item  Restart and reconnect the client programs.
\end{enumerate}
If this fails (even after a second) time there may be a network problem which
can not be resolved by simple means.

\section{ 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'
% html: Beginning of file: `dmco.htm'

\chapter{DMC Command Summary}

\label{f19}
 


\section{Most Used Commands}


\begin{description}
\item[drive a4 value] (cf.\ Section~\ref{f9}) Drives the detector to a new 2 Theta value. Be careful and watch out for
rubbish trying to block the detectore pass through the experiment hall.
\item[drive lambda value.] Drives the wavelength to a new value. The whole instrument is going to
move. Add 10 extra levels of care to the above when doing this. 
\item[ count mode preset] (cf.\ Section~\ref{f18})  Counts in mode with a preset value of preset. Stores data automatically.
\item[ Repeat num mode preset]  Calls count num times. 
\item[FileEval filename] (cf.\ Section~\ref{f7})  Runs a  batch file with the specified filename. 
\end{description}
 
\section{Driving}



\begin{description}\item[drive mot1 NewVal mot2 NewVal ....] (cf.\ Section~\ref{f9}) Drives motors. Followed by pairs of motor names and new values.
\item[run mot1 NewVal mot2 NewVal ....]  Runs motors. 
\end{description}
Known motors are: OmegaA, A1, TwoThetaM, A2, MonoX, MonoY, MonoChi, MonoPhi,
CurveM, Table, A3, TwoThetaD, A4.

\section{ Counting }



\begin{description}\item[banana CountMode \hbox{$[$}NewVal\hbox{$]$}] (cf.\ Section~\ref{f15}) Without a parameter displays the current counting mode. With parameter sets 
the count mode. Possible values are Timer for waiting for time or Monitor for 
waiting for a monitor.
\item[banana preset \hbox{$[$}NewVal\hbox{$]$}]  Without a parameter displays the current preset for either time or monitor.
With a parameter sets the preset.
\item[banana count]  Starts counting.
\item[StoreData] (cf.\ Section~\ref{f18})  Writes the current state of DMC to a NeXus file.
\item[ count mode preset] (cf.\ Section~\ref{f18})  Counts in mode with a preset of preset. Stores data automatically.
\item[ Repeat num mode preset]  Calls count num times. 
\end{description}

\section{R\"unbuffer}



\begin{description}\item[ Buf new name] (cf.\ Section~\ref{f8}) New buffer name
\item[Buf copy name1 name2]  copies buffers.
\item[Buf del name]  deletes buffer.
\end{description}
Buffers created with Buf new name are installed as command name and understand:
\begin{description}
\item[NAME append bla bla .......] Append text to buffer
\item[NAME del iLine]  Deletes line.
\item[ NAME ins iLine bla bla ....] Inserts text after line.
\item[NAME print] prints contents of buffer to screen.
\item[NAME save file]  Saves buffer to file.
\item[NAME read file]  Read buffer contents from file.
\item[NAME run] Executes contents of buffer.
\end{description}
There can be a stack of R\"unbuffers.
\begin{description}
\item[RuLi add buffer] Adds an buffer to the stack.
\item[RuLi list]  Lists the stack.
\item[RuLi del line]  Deletetes buffer from stack.
RuLi ins iLine name
 Inserts name after iLine.
\item[ RuLi run]  Executes Stack.
\item[ RuLi batch]  Executes stack permanently. New buffers may be added.
\end{description}
 
\section{ General commands }



\begin{description}\item[Success] (cf.\ Section~\ref{f9})  wait for the last operation to finish.
\item[wait time] (cf.\ Section~\ref{f4})  wait for time to pass....
\item[Dir ] (cf.\ Section~\ref{f4})  lists all objects in the system.
\item[config Rights username password] (cf.\ Section~\ref{f6})  changes authorisation to that of the user identified by username,
password.
\item[FileEval filename] (cf.\ Section~\ref{f7})  executes batch file filename.
\end{description}

\section{ Log Files}



\begin{description}\item[LogBook file name] (cf.\ Section~\ref{f10})  sets log file name
\item[ LogBook on]  switches logging on
\item[LogBook off]  closes LogBook
\item[LogBook]  lists current logging status
\end{description}

\section{ Variables}



Each variable (cf.\ Section~\ref{f18})
 can be inquired by just typing its name. It can be set by
typing the name followed by the new value. Currently available variables
are:
\begin{itemize}
\item Title
\item User
\item comment1
\item comment2
\item comment3
\item User
\item adress
\item phone
\item email
\item Sample
\item sample\_mur
\end{itemize}

% html: End of file: `dmco.htm'

\end{document}