TCPClose

Syntax

TCPClose (socket[,option {Default zero for complete;1 for partial;2 for abort}]) Returns status

Description

Note: The flag is set according to whether Omnis was able to make a call to this external command.

This Web command is multi-threaded, allowing another thread to execute in the multi-threaded server while it runs. Note that the same socket cannot safely be used concurrently by more than one thread.

TCPClose closes, and depending on the Option, releases a Socket. When the socket is connected, this will result in the closure of the connection to the remote application. All new sockets returned by all Web commands, must eventually be released using TCPClose, to avoid resource leakage.

The most brutal form of TCPClose is an abortive close. In this case, no consideration is given to the state of the connection, or exchanges with the remote application, and the socket is closed and released immediately. This form of TCPClose is recommended for use in error handling situations.

The mildest form of TCPClose is a partial close. In this case, the socket is not released, and you will need to call TCPClose again to release the socket. A partial close initiates a disconnect of the TCP/IP connection, by sending a TCP/IP packet with the finish flag set. This means that you can no longer send data to the remote application, but you can continue to receive data. The remote application will be informed of the partial close, when it receives zero bytes; in the case of the TCPReceive command, it will return a received character count of zero. At this point, the remote application can continue to send data, and when it has finished, it issues a complete close itself.

The remaining form of TCPClose is a complete close. In this form, TCPClose initiates a close of the connection if necessary, receives data on the connection until no more is available (to flush the connection), and releases the socket. This is recommended practice for TCP/IP connections.

What does this mean in practice? Consider two applications A1 and A2, communicating using TCP/IP. A1 can either do a partial close or a complete close. In both cases, A2 will receive zero bytes, indicating that disconnection has been initiated. A2 can continue to send, and when it has finished, it issues a complete close. A1 can receive the data sent by A2 provided that it only issued a partial close. Eventually A1 will receive zero bytes, at which point it issues a final complete close. At this point, the connection has been gracefully closed, and the sockets used by both A1 and A2 have been released.

Socket is an Omnis Long Integer field containing a number representing a previously opened socket.

Option is an optional Omnis Integer field, which has the value zero for a complete close, 1 for a partial close, and 2 for an abortive close. If omitted, it defaults to a complete close.

Status is an Omnis Long Integer field which receives the value zero for success, or an error code < 0 for failure. Possible error codes are listed in the Web Command Error Codes Appendix.

Example

# Close the socket bound to iPort
Calculate iPort as  6000
TCPSocket Returns iSocket
TCPBind (iSocket,iPort) Returns lStatus

TCPClose (iSocket)