tcp.reader

function

Library: TCP/IP client and server support (OMTCP)
Import : omtcp.xmd

Returns: An external source containing the data read from the tcp connection.


Declaration
define external string source function 
   tcp.reader of       value tcp.connection  connection
              timeout  value integer         ms         optional
              protocol value tcp.io-protocol protocol   optional

      

Argument definitions

connection
is an existing tcp.connection object.
ms
is the time to wait for a read operation to complete, expressed in milliseconds.
protocol
specifies which I/O protocol is to be used.


Purpose

Use tcp.reader to obtain an external source object from which data will be read.

Requirements

connection must exist, or else an external exception with identity TCP05 is thrown.

There may not be an active external source derived from connection with tcp.reader, or else and external exception with identity TCP04 is thrown.

Usage Notes

If the received packet is corrupted, an external exception with identity TCP13 is thrown.

The timeout value applies primarily to data read from the returned external source. If a read operation times out, an external exception with identity TCP07 is thrown.

tcp.reader can be called more than once for a connection. All such derived sources read from the same source attachment, but such sources are subject to read-ahead, and it is generally the case that a read from a source will actually capture more data than is needed for immediate use. This means that if there are two or more sources derived from a connection, it is usually the case that data read from one such source is not that which immediately follows that read from another such source. As a consequence, only ONE external source can be derived from a connection at a time. That is, sources must be derived serially.

Example

The following example shows how to output to #main-output data that is read from a TCP connection.

  import "omtcp.xmd" prefixed by tcp.
  
  process
     local tcp.connection connection
  
     set connection to tcp.connect to "localhost" on 5300
     tcp.set-buffering of connection enabled false
  
     output tcp.reader of connection protocol tcp.multi-packet