  
  [1X3 Using streams[0X
  
  The  package  implements  new  kind  of  [5XGAP[0m  input-output  streams,  called
  input-output  TCP  streams.  Such streams are based on the functionality for
  the TCP/IP protocol usage provided by the [5XGAP[0m package [5XIO[0m, and may constitute
  an independent interest for [5XGAP[0m users.
  
  Input-output TCP streams are intended to support all operations, implemented
  for  streams  in  [5XGAP[0m.  It  is  assumed that all existing code using streams
  should  work  with  this kind of streams as well (please let us know, if you
  will  notice  that  this  is  not  the  case!).  We  installed  methods  for
  input-output  TCP  streams  to  support  the  following operations: [10XViewObj[0m,
  [10XPrintObj[0m,  [10XReadByte[0m,  [10XReadLine[0m,  [10XReadAll[0m,  [10XWriteByte[0m,  [10XWriteLine[0m,  [10XWriteAll[0m,
  [10XIsEndOfStream[0m, [10XCloseStream[0m, [10XFileDescriptorOfStream[0m, [10XUNIXSelect[0m.
  
  
  [1X3.1 Input-output TCP streams[0X
  
  [1X3.1-1 IsInputOutputTCPStream[0m
  
  [2X> IsInputOutputTCPStream______________________________________________[0Xfilter
  
  [10XIsInputOutputTCPStream[0m  is  a subcategory of [10XIsInputOutputStream[0m. Streams in
  the  category  [10XIsInputOutputTCPStream[0m  are  created  with  the  help  of the
  function  [2XInputOutputTCPStream[0m ([14X3.1-4[0m) with one or two arguments dependently
  on whether they will be used in the client or server mode. Examples of their
  creation and usage will be given in subsequent sections.
  
  [1X3.1-2 IsInputOutputTCPStreamRep[0m
  
  [2X> IsInputOutputTCPStreamRep___________________________________________[0Xfilter
  
  This  is  the  representation  that  is  used  for  streams  in the category
  [10XIsInputOutputTCPStream[0m.
  
  [1X3.1-3 InputOutputTCPStream[0m
  
  [2X> InputOutputTCPStream( [0X[3Xsocket_descriptor[0X[2X ) ________________________[0Xfunction
  [6XReturns:[0X  stream
  
  Returns a stream in the category [10XIsInputOutputTCPStream[0m for the given socket
  descriptor  that  will  be  used  to accept incoming connections. An example
  demonstrating this will be given after the next section.
  
  However,   the   service  provider  much  likely  will  create  such  stream
  automatically   inside  the  function  [2XRunSCSCPserver[0m  ([14X5.2-1[0m)  rather  then
  manually.
  
  [1X3.1-4 InputOutputTCPStream[0m
  
  [2X> InputOutputTCPStream( [0X[3Xhostname, port[0X[2X ) ___________________________[0Xfunction
  [6XReturns:[0X  stream
  
  Returns a stream in the category [10XIsInputOutputTCPStream[0m that will be used by
  the client for communication with the specified server and port.
  
  
  [1X3.2 Example of client-server communication via input-output TCP streams[0X
  
  The  following example demonstrates an interaction between client and server
  using input-output TCP stream, and shows how such streams are created in the
  function [2XRunSCSCPserver[0m ([14X5.2-1[0m). It uses some functions from the [5XIO[0m package,
  see  the [5XIO[0m manual for their description. Now we will show step by step what
  is  happens  on  server and client (of course, if you will try this example,
  the numbers denoting descriptors may be different).
  
  Firts,  we  will start two [5XGAP[0m sessions, one for the server, another one for
  the client. Now we enter the following commands on the server's side:
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> sock := IO_socket( IO.PF_INET, IO.SOCK_STREAM, "tcp" );[0X
    [4X3[0X
    [4Xgap> lookup := IO_gethostbyname( "localhost" );[0X
    [4Xrec( name := "localhost", aliases := [  ], addrtype := 2, length := 4, [0X
    [4X  addr := [ "\177\000\000\>" ] )[0X
    [4Xgap> port:=26133;[0X
    [4X26133[0X
    [4Xgap> res := IO_bind( sock, IO_make_sockaddr_in( lookup.addr[1], port ) );[0X
    [4Xtrue[0X
    [4Xgap> IO_listen( sock, 5 );[0X
    [4Xtrue[0X
    [4Xgap> socket_descriptor := IO_accept( sock, IO_MakeIPAddressPort("0.0.0.0",0) );[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  After  the  last  command you will not see the [5XGAP[0m prompt because the server
  starts  to  wait  for an incoming connection. Now we go to the client's side
  and  create an input-output TCP stream to the server. Here it can be created
  in one step:
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> clientstream:=InputOutputTCPStream( "localhost", 26133 );[0X
    [4XCreating a socket...[0X
    [4XConnecting to a remote socket via TCP/IP...[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  Now  we  are  trying to connect to the server, and as soon as the connection
  will  be  established, the stream will be created at the client side, and we
  will see the output and the new [5XGAP[0m prompt:
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4X< input/output TCP stream to localhost >[0X
    [4Xgap>[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  On  the  server you will get the socket descriptor and then you will be able
  to create a stream from it:
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4X4[0X
    [4Xgap> serverstream := InputOutputTCPStream( socket_descriptor );[0X
    [4X< input/output TCP stream to socket >[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  Now  we can write to this stream on the client side and then read from it on
  the server side and backwards. First, write on the client:
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> WriteLine( clientstream, "12345" );[0X
    [4Xtrue[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  Now read and write on the server:
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> ReadLine( serverstream );[0X
    [4X"12345\n"[0X
    [4Xgap> WriteLine( serverstream, "54321" );[0X
    [4Xtrue[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  And finally we read on the client and close the stream:
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> ReadLine( clientstream );[0X
    [4X"54321\n"[0X
    [4Xgap> CloseStream( clientstream );[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  and similarly close the stream on the server:
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> CloseStream( serverstream );[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
