define external function TCPConnectionClose
        value TCPConnection this-TCPConnection
  as TCPConnectionClose

This function closes a TCP connection object. While it is valid to close a TCP connection object that is already closed or which never was connected, in both these cases TCPConnectionClose does nothing.

Once a TCP connection has been closed by TCPConnectionClose, then any read or write operation on an external source or output derived from it is in error.

Note that allowing an OmniMark TCPConnection variable to go out of scope (exiting a local scope for a local variable, or exiting the OmniMark program for a global variable), in the absence of other references to the TCP connection, has the effect of doing a TCPConnectionClose on the variable. As long as TCPConnection variables are declared at a scope level that corresponds to the lifetime of the connection (which is good programming practice), there is never any need to use TCPConnectionClose.

If global external sources and/or outputs have been derived from a local TCP connection variable, they constitute references to the TCP connection, so that local TCP connection variables going out of scope do not by themselves cause a TCP connection to close. It is only when all of these external outputs and sources themselves are discarded (generally by their going out of scope), that the connection to which they are attached is finally closed.

Finally, it is good programming practice to have the scope of external sources and outputs derived from a TCP connection be no more global than that of the TCP connection. If this is done, then the programmer doesn't have to worry about the effect of the derived sources and outputs on the lifetime of the connection.

Argument:

• "this-TCPConnection" is an opaque object of type TCPConnection.

Example:

  local TCPConnection client

  set client to TCPConnectionOpen on "123.123.123.45" at 5600
  ;do something with the connection
  ;communicate with the server
  TCPConnectionClose client