Sockets

 read text data from a socket connection

Parameters

 sid - valid open socket ID timeout - (optional) non-negative integer; specify a timeout in seconds

Description

 • The procedure Read is used to read textual data in the form of Maple strings from a socket connection.
 • The argument sid must be a valid socket ID for an open socket connection. An optional timeout argument can be passed, which is taken to be the number of seconds to wait before timing out the read operation.
 • When called, Read blocks indefinitely until data becomes available on the socket sid at which time the available data (up to a system dependent maximum number of bytes) is read. Data read from the socket is returned as a Maple string. If called with the timeout parameter and no data becomes available on the socket sid within the specified number of seconds, then the Read operation returns false.
 • Calls of the form Read( sid, 0 ) immediately return the value false.
 • Because Maple strings cannot contain null bytes, Read should be used only when you are sure that the data coming in over the network consists of plain ASCII text. (This is frequently the case.) If data may contain null bytes, then you should use Sockets[ReadBinary] instead.
 • The Read procedure obeys the persistent timeout protocol. (See Sockets/timeout.)

Examples

This example illustrates how data may appear to be lost if it contains null bytes.

 > $\mathrm{with}\left(\mathrm{Sockets}\right):$
 > $\mathrm{sid}≔\mathrm{Open}\left("mantis","echo"\right)$
 ${0}$ (1)
 > $\mathrm{data}≔\left[\mathrm{op}\left(\mathrm{convert}\left("Hi",'\mathrm{bytes}'\right)\right),0,\mathrm{op}\left(\mathrm{convert}\left("there",'\mathrm{bytes}'\right)\right)\right]$
 ${\mathrm{data}}{≔}\left[{72}{,}{105}{,}{0}{,}{116}{,}{104}{,}{101}{,}{114}{,}{101}\right]$ (2)
 > $\mathrm{datalen}≔\mathrm{nops}\left(\mathrm{data}\right):$
 > $\mathrm{data}≔\mathrm{Array}\left(\mathrm{data},'\mathrm{datatype}'='\mathrm{integer}'\left[1\right]\right)$
 ${\mathrm{data}}{≔}\left[\begin{array}{cccccccc}{72}& {105}& {0}& {116}& {104}& {101}& {114}& {101}\end{array}\right]$ (3)
 > $\mathrm{WriteBinary}\left(\mathrm{sid},\mathrm{data}\right)$
 ${8}$ (4)
 > $\mathrm{Read}\left(\mathrm{sid}\right)$
 ${"Hi"}$ (5)
 > $\mathrm{WriteBinary}\left(\mathrm{sid},\mathrm{data}\right)$
 ${8}$ (6)
 > $a≔\mathrm{Array}\left(1..\mathrm{datalen},'\mathrm{datatype}'='\mathrm{integer}'\left[1\right]\right)$
 ${a}{≔}\left[\begin{array}{cccccccc}{0}& {0}& {0}& {0}& {0}& {0}& {0}& {0}\end{array}\right]$ (7)
 > $\mathrm{ReadBinary}\left(a,\mathrm{sid}\right)$
 ${8}$ (8)
 > $a$
 $\left[\begin{array}{cccccccc}{72}& {105}& {0}& {116}& {104}& {101}& {114}& {101}\end{array}\right]$ (9)
 > $\mathrm{Close}\left(\mathrm{sid}\right)$
 ${\mathrm{true}}$ (10)

The underlying problem is that Maple strings cannot contain null bytes.

 > $\mathrm{convert}\left(\mathrm{data},'\mathrm{list}'\right)$
 $\left[{72}{,}{105}{,}{0}{,}{116}{,}{104}{,}{101}{,}{114}{,}{101}\right]$ (11)
 > $\mathrm{convert}\left(,'\mathrm{bytes}'\right)$
 ${"Hi"}$ (12)