SocketIO

     NAME
	  socketio - Socket based input/output operations

     DESCRIPTION
	  This class implements	input and output operations on
	  sockets, used	in both	Client and Server ends.	There is a
	  primitive I/O	pair Read/Write, just shipping bytes, and a
	  slightly more	sophisticated pair of operations:
	  InRecord/OutRecord that communicates variable	size Texts
	  over the pipe.

     EXAMPLES
	  See the users	manual in simioprocess.ps

     AUTHOR
	  Boris	Magnusson, Lund	Institute of Technology.

     DETAILED INTERFACE
	     SocketBasics class	SocketIO;
	  The Read/Write  operations  are  directly  calling  the  I/O
	  operations   provided	  for	Sockets.  They	are  thus  not
	  supporting any structure on the communication, but this  has
	  to  be  implemented  by  the	application.  One Write	can be
	  matched by many Reads	(using	smaller	 buffers)  or  several
	  Writes  can  be  matched by one Read (e.g. if	the reader has
	  been delayed). The Read/Write	 operations  can  be  used  to
	  write	Simula programs	communicating with existing servers or
	  clients.

	  In many cases	the communication is structured	as an exchange
	  of  messages.	OutRecord/InRecord supports this organization.
	  One call to OutRecord	on the sending side always  match  one
	  call of InRecord on the receiving side. These	operations use
	  a specific format of the messages and	 are  only  useful  if
	  there	 are  Simula  programs	in  both ends (or if a program
	  written in another language can be adapted to	use  the  same
	  format).

	  A call to Read or InRecord will hang if there	 are  no  data
	  available.	The  functionality  provided  by  the  library
	  SimIOProcess can be used to avoid calling  these  operations
	  until	 data  is  actually  present  (and  thus  avoiding the
	  possible hang). See this library for details.

	  SocketIO is an abstract class	with two concrete  subclasses:
	  ClientSocket and ServerSocket.

	   Super: SocketBasics;
	   Kind: Abstract;
	   Subclasses: ClientSocket and	ServerSocket;
	   Init: see subclasses;
	   Sequencing: see subclasses;
     OPERATIONS
     Write
	     integer procedure Write(T);
	     text T; ! the bytes to send;
	  Write	the content of T to the	Socket.	Return number of bytes
	  actually written. Returns <0 it there	is a problem, like the
	  program in the other end did close its Socket.

     Read
	     integer procedure Read(T);
	     text T; ! Text to fill, its length	is max to read;
	  Attempt to fill T with info info read	from the Socket. Waits
	  unitl	 info  available. Returns, N, number of	bytes read and
	  stored in T.sub(1,N).	Returns	<=0 if	there  is  a  problem,
	  like	the program in the other end did close its Socket. The
	  OS often enforce a maximum size  of  messages	 that  can  be
	  returned in one go, like 4096bytes under Unix. In such cases
	  long messages	must be	read by	several	calls to Read.

     OutRecord
	     boolean procedure OutRecord(T);
	     text T; ! the info	to send;
	  Send a sequence of bytes of information to  the  other  end.
	  The  info  in	 T  might be a readable	ASCII sequence or some
	  binary information.  Returns True if all info	send OK.

     InRecord
	     text procedure InRecord(T);
	     text T; ! Suggested buffer	for received message.;
	  Wait for and read the	next message from  the	Socket.	 T  is
	  used	for the	message	if long	enough,	if not a new buffer is
	  allocated.  The result of InRecord is	either the new	buffer
	  or a subtext of T containing the received information.

     Endfile
	     Boolean procedure Endfile;
	  Return true if  last	I/O  operation	did  not  input/output
	  anything.   This  happens if the program in other end	closed
	  his socket (or died),	but also in other situations.