PSI sics-cvs-psi_pre-ansto

doc/programmer/proto.tex

@@ -0,0 +1,61 @@
+\chapter{The SICS Server Client Protocol}
+This short chapter describes the command protocol between the SICS server
+and  possible SICS clients. All this is very simple.
+
+\section{Logging in to the SICS Server}
+In order to log in to the SICS server it needs to be known on which
+machine the server runs and at which port number the server listens for
+connection requests. Also needed is a valid username/ password pair for the
+SICS server in question. Given that the procedure for connecting to a SICS
+server requires the following steps:
+\begin{enumerate}
+\item Open a TCP/IP connection to the SICS server port at the machine 
+where it is running.
+\item Immediately after opening the connection send the username/password
+pair. If everything is OK, a string OK is sent. Else the server will break
+the connection again. 
+\end{enumerate}
+
+\section{Sending Commands}
+After login, two means of communications exist. The communication
+protocoll is choosen through the server port the client connects too. 
+ The recommended way is
+to adhere to the telnet protocoll as described in RFC-854. Just a
+basic NVT (Network Virtual Terminal) with no options is
+implemented. Binary communication is not possible on a telnet port. 
+
+The older way of communication is to send commands directly on the
+TCP/IP port.  Commands are strings terminated by a \verb+\n+. Return 
+messages from the server have the same format.  This scheme is
+obsolete but it has been left in because the need for a binary
+communication may arise and this would help implement such a thing. 
+
+
+
+For a list of possible commands consult the
+user documentation.
+
+\section{Issuing Interrupts}
+In some cases a user might want to stop the operation of the server. In
+order to do this the client must send an interrupt to the SICS server. There
+are two ways to do this: through the normal connection socket and through
+the a special UDP message to the server. Let us first discuss the first
+method, which uses the normal command socket for sending an interrupt.
+
+In order to send an interrupt through the normal command socket a special
+message must be sent, consisting of a special command string. The command
+string is again all ASCII. The first part of this command string must read:
+INT1712, followed by a number denoting the interrupt. The meaning of these
+numbers is resolved in file interrupt.h. For example, the string 'INT1712 2'
+will abort the current scan. The presence of an interrupt string will be
+checked for already by the network reader. This means that such interrupts
+will even be honored when the client connection is waiting for some hardware
+to finish its job and would not accept normal commands. \label{prot1}
+
+The SICS server also checks a special TCP/IP port for UDP messages which
+denote an interrupt. In order to send an interrupt through this channel, a
+UDP connection to the SICS servers UDP port must be opened. Then an special
+ASCII string of the form: {\bf SICSINT num} must be sent. num must be
+replaced by the number of the interrupt to issue. Again interrupt codes are
+resolved in file interrupt.h.  
+