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

Return type: String Returns:

Declaration

define external stream function tcp.get-string
    from        value tcp.connection Connection
    size        value integer        MinRead    optional
    up-to       value integer        MaxRead    optional
    timeout     value integer        ms         optional

Argument definitions

Connection

is a tcp.connection object representing an existing connection.

MinRead

is the minimum number of characters to read.

MaxRead

is the maximum number of characters to read.

ms

is how long the function will wait for at least one character, expressed in milliseconds.

Use tcp.get-string to return characters received from a source on the TCP connection object.

Requirements

Connection must represent an existing connection (else external exception TCP05).

There must not be an active external source derived from Connection with tcp.reader (else external exception TCP04).

If MinRead is specified, it must have a value of -1 or greater (else external exception TCP03).

If MaxRead is specified, it must have a value of -1 or greater (else external exception TCP03).

If both MinRead and MaxRead are specified, MinRead must have a value less than the value of MaxRead (else external exception TCP03).

Usage Notes

If an error occurs during the read, external exception TCP11 is thrown.

If the read operation times out, external exception TCP07 is thrown.

If neither MinRead nor MaxRead is specified the function reads as many characters as are available, as long as there is at least one character.

Specifying value of -1 for either MinRead or MaxRead indicates no limit. (This is the default value for both parameters.)

Sequential uses of tcp.get-string and tcp.reader are allowed. It is also guaranteed that tcp.get-string will only ever read the characters it returns from a source. Any following characters are available to the next tcp.get-string or tcp.reader.

Example #1

  import "omtcp.xmd" prefixed by tcp.
  
  process
     local tcp.connection Connection-1
  
     set Connection-1 to tcp.connect to "localhost" on 5300
     output tcp.get-string from Connection-1

Example #2

  import "omtcp.xmd" prefixed by tcp.
  
  process
     output tcp.get-string from tcp.connect to "localhost" on 5300
        size 10

Related Syntax    tcp.disconnect    tcp.writer    tcp.peer-ip    tcp.peer-name    tcp.reader    tcp.wait-for-input    tcp.is-connected    tcp.put-string    tcp.connect    tcp.set-buffering    tcp.terminate-reader

Other Library Functions    tcp.accept-connection    tcp.connect    tcp.connection    tcp.create-service    tcp.destroy-service    tcp.disconnect    tcp.end-delimited    tcp.get-string    tcp.is-connected    tcp.multi-packet    tcp.omtcp-version    tcp.peer-ip    tcp.peer-name    tcp.port    tcp.put-string    tcp.reader    tcp.service    tcp.set-buffering    tcp.single-packet    tcp.terminate-reader    tcp.wait-for-input    tcp.writer

[ INDEX ] [ CONCEPTS ] [ TASKS ] [ SYNTAX ] [ LIBRARIES ] [ LEGACY LIBRARIES ] [ ERRORS ]