swirl
Guide to OmniMark 8   OmniMark home
docs home 
IndexConceptsTasksSyntaxLibrariesLegacy LibrariesErrors
 
  Related Syntax     Other Library Functions  
function  

TCPConnectionGetLine

 
 

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


Purpose

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:

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
 
 

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

OmniMark 8.2.0 Documentation Generated: March 13, 2008 at 3:27:39 pm
If you have any comments about this section of the documentation, please use this form.

Copyright © Stilo International plc, 1988-2008.