\subsection{RS232 Controller}
This class provides the basic communication facilities for an arbitrary
 controller which is connected through a RS-232 cable to a terminal 
 server. This class bypasses David Maden's SerPortServer program. Also this 
 code may be useful for any other controller connected to a TCP/IP
 network.  Basic facilities are provided for writing data to such a device 
 and to read from 
 it. Morevoer there are utility functions for the common case when the 
 device is to send some data terminated with a specified terminator.
 Timeouts are also observed on reading operations. It is required that this
 controller accesses a binary port and not a port which uses some kind of
 telnet negotiation.  


 This classes data structure:

@d rs232dat @{
	typedef struct{
			pObjectDescriptor pDes;
			char *sendTerminator;
			char *replyTerminator;
			int timeout;
			mkChannel *pSock;
			char *pHost;
			int iPort;
                      } rs232, *prs232;

@}
The fields are:
\begin{description}
\item[pDes] The standard object descriptor.
\item[sendTerminator] The terminator with which to terminate any command.
\item[replyTerminator] The terminator expected to end a transmission from the
 device.
\item[timeout] A timeout for reading in microseconds.
\item[mkChannel] Our very own structure for a network connection.
\item[pHost]The host (mostly the terminal server) to connect to.
\item[iPort] The port at host to which to connect.
\end{description}

The following interface functions are provided: 

@d rs232int @{
	int RS232Action(SConnection *pCon, SicsInterp *pSics,
			void *pData, int argc, char *argv[]);
	int RS232Factory(SConnection *pCon, SicsInterp *pSics,
			void *pData, int argc, char *argv[]);

	void setRS232SendTerminator(prs232 self, char *term);
	void setRS232ReplyTerminator(prs232 self, char *term);
        void setRS232Timeout(prs232 self, int timeout);
	int writeRS232(prs232 self, void *data, int dataLen);
	int readRS232(prs232 self, void *data, int *dataLen);
	int availableRS232(prs232 self);
	int transactRS232(prs232 self, void *send, int sendLen,
				void *reply, int replylen);
	void getRS232Error(int iCode, char *errorBuffer, 
                                             int errorBufferLen);
        int initRS232(prs232 self);
@}

All functions take a pointer to their daat structure as a parameter.
When the functions return an integer, 1 measn successful completion, 
 anything else is an error code if not stated otherwise. 
The functions have the following meanings:
\begin{description}
\item[RS232Action] The interpreter interface functon for the controller.
\item[RS232Factory] The factory function for configuring an interpreter.
\item[setRS232SendTerm] sets the terminator with which each command is
  terminated.
\item[setRS232ReplyTerminator] sets the expected terminator in a reply from
 the device.
\item[setRS232Timeout] sets the timeout for reading from the device. The value
 is in microseconds.
\item[writeRS232] writes dataLen bytes from data to the device.
\item[readRS232] reads at max dataLen bytes from the device. dataLen is set
 to the actual number of bytes read.
\item[transactRS232] sends sendLen bytes from send to the device and then 
 reads from the device until the reply terminator has been found. At max
 replyLen bytes of reply are copied to reply.
\item[availableRS232] returns 1 if data is available, o if none is available 
 and a negative value if an error occurs.
\item[getRS232Error] gets a string representation for the error code 
 iCode.
\item[initRS232] tries to close and reopen the RS232 connection. This is 
 useful for the automatic fixing of communication problems encountered.
\end{description}

@o rs232controller.h @{
/*---------------------------------------------------------------------
	         R S 2 3 2 C o n t r o l l e r
  
  A general object which represents a controller connected to the network
  via a terminal server. This bypasses David Maden's SerPortServer software.
  Basic facilities are provided for writinga nd reading to and from the 
  device. For more information see the rs232controller.tex file.

  copyright: see copyright.h

  Mark Koennecke, October 2001
-----------------------------------------------------------------------*/
#ifndef RS232CONTROLLER
#define RS232CONTROLLER
#include "network.h"

/*----------------------- a data structure ----------------------------*/
@<rs232dat@>

/*----------------------- the interface functions --------------------*/
@<rs232int@>

#endif
@}