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

TCPConnectionGetCharacters

 
 

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

Characters read from the TCP connection.


Declaration

  define external stream function TCPConnectionGetCharacters
      value       TCPConnection this-TCPConnection
      size        value         integer minimum-read-length      optional
      variable-to value         integer maximum-read-length      optional
      timeout     value         integer timeout-in-milliseconds optional
   as TCPConnectionGetCharacters


Purpose

This function reads characters received from a source on the TCP connection object.

There are four combinations for specifying the size and variable-to values, as follows:

  1. If neither is specified, then TCPConnectionGetCharacters returns as many characters as it has available, as long as it has at least one character. It will wait (only for as long as the timeout value if one is specified) for at least one character, only if it has no characters to return.
  2. If only the size value is specified, TCPConnectionGetCharacters reads and returns exactly minimum-read-length characters. If a timeout value is specified and is exceeded, it will return immediately with the (zero or more) characters it has available. It will also set the TCP connection to be in error.
  3. If only the variable-to value is specified, then TCPConnectionGetCharacters reads as many characters as it has available, as if neither size nor variable-to were specified, except that if it has more than maximum-read-length available, it will only return maximum-read-length and will save any remaining characters for a subsequent read.
  4. If both the size and variable-to values are specified, then TCPConnectionGetCharacters reads at least minimum-read-length characters, but will return up to maximum-read-length characters, if it has them available. Like the size value only case, it can timeout in reading the first minimum-read-length characters, but will not do so once that many have been read. It is an error for the size value to be greater than the variable-to value.

If the passed TCP connection object is closed or was never connected, then this function returns zero characters. At the same time, it sets the TCP connection to be in error. If an error is encountered during reading, either zero characters or those already read (if any) are returned, as seems appropriate, and 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 TCPConnectionGetCharacters when a TCPConnectionGetSource derived source is also active. Note, however, that sequential uses of TCPConnectionGetCharacters are allowed. It is also guaranteed that a TCPConnectionGetCharacters 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 TCPConnectionGetCharacters when the associated TCP connection has been closed using TCPConnectionClose is in error, and will set the TCP connection to be in error.

Any attempt to do a TCPConnectionGetCharacters 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 TCPConnectionGetCharacters TCP-Conn
  again

    Related Syntax
   TCPConnectionGetSource
   TCPConnectionGetLine
 
  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 ] [ LEGACYLIBRARIES ] [ ERRORS ]

OmniMark 7.1.2 Documentation Generated: June 28, 2005 at 5:45:51 pm
If you have any comments about this section of the documentation, send email to [email protected]

Copyright © Stilo Corporation, 1988-2005.