Library: TCP/IP client and server support (OMTCP) original Include: omtcp.xin

Return type: String Returns:  Characters up to and including the next line-end sequence.

Declaration

  define external stream function TCPConnectionGetLine
      value     TCPConnection this-TCPConnection
      multiline value         switch             read-to-double-line-end optional initial {false}
      timeout   value         integer       timeout-in-milliseconds optional
  as TCPConnectionGetLine

This function reads up to and including the next line-end sequence ("%13#%10#", or "%10#), or the next pair of line-end sequences if the multiline value is true, and returns the read characters.

The returned characters are "normalized" as follows:

1. All line-end sequences are replaced by "%13#%10#".
2. The trailing line-end sequence in the multiline case is removed, so that there is only one line-end sequence at the end.

If a timeout value is set and then exceeded, either zero characters are returned or only those available, as seems appropriate. The TCP connection object is set to be in error.

Note that difficulties inherent in deriving multiple sources from a connection apply equally to using TCPConnectionGetLine when a TCPConnectionGetSource derived source is also active. However, sequential uses of TCPConnectionGetLine are safe. It is also guaranteed that a TCPConnectionGetLine will only ever read the characters it returns from a source. Any following characters are available to the next TCPConnectionGetSource, TCPConnectionGetCharacters, or TCPConnectionGetLine.

Any attempt to do a TCPConnectionGetLine when the associated TCP connection object has been closed using TCPConnectionClose is in error.

Any attempt to do a TCPConnectionGetLine when there is already an active source derived from TCPConnectionGetSource is not allowed, and will result in an OmniMark external function exception.

Arguments:

• "this-TCPConnection" is an OMX component of type TCPConnection.
• "read-to-double-line-end" is a switch value that has a default value of "false".
• "timeout-in-milliseconds" is an optional integer value which indicates the number of milliseconds the connection will wait before terminating.

Example

  local TCPConnection TCP-Conn

  set TCP-Conn to TCPConnectionOpen on "localhost" at 5300

  repeat
     exit unless TCPConnectionIsConnected TCP-Conn
     output TCPConnectionGetLine TCP-Conn
  again

Related Syntax    TCPConnectionGetSource    TCPConnectionGetCharacters

Other Library Functions    TCPConnection    TCPConnectionClose    TCPConnectionGetCharacters    TCPConnectionGetLine    TCPConnectionGetOutput    TCPConnectionGetPeerIP    TCPConnectionGetPeerName    TCPConnectionGetSource    TCPConnectionGetStatusReport    TCPConnectionHasCharactersToRead    TCPConnectionIsConnected    TCPConnectionIsInError    TCPConnectionOpen    TCPConnectionPut    TCPConnectionSetBuffering    TCPConnectionSignalSourceEnd    TCPIsVersionCompatible    TCPLibraryVersion    TCPService    TCPServiceAcceptConnection    TCPServiceClose    TCPServiceGetPort    TCPServiceGetStatusReport    TCPServiceIsInError    TCPServiceIsOpen    TCPServiceOpen    TCPTraceConnectionOpen

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