open_connection Function

This function opens a TCP/IP connection to a specified service.

Syntax

UTL_TCP.OPEN_CONNECTION  (remote_host      IN VARCHAR2,
                          remote_port      IN PLS_INTEGER,
                          local_host       IN VARCHAR2 DEFAULT NULL,
                          local_port       IN PLS_INTEGER DEFAULT NULL,
                          in_buffer_size   IN PLS_INTEGER DEFAULT NULL,
                          out_buffer_size  IN PLS_INTEGER DEFAULT NULL,
                          charset          IN VARCHAR2 DEFAULT NULL,
                          newline          IN VARCHAR2 DEFAULT CRLF,
                          tx_timeout       IN PLS_INTEGER DEFAULT NULL)
                          RETURN connection;

Parameters

Table 83-4 open_connection Function Parameters

Parameter	Description
remote_host (IN)	The name of the host providing the service. When remote_host is NULL, it connects to the local host.
remote_port (IN)	The port number on which the service is listening for connections.
local_host (IN)	The name of the host providing the service. NULL means don't care.
local_port (IN)	The port number on which the service is listening for connections. NULL means don't care.
in_buffer_size (IN)	The size of input buffer. The use of an input buffer can speed up execution performance in receiving data from the server. The appropriate size of the buffer depends on the flow of data between the client and the server, and the network condition. A 0 value means no buffer should be used. A NULL value means the caller does not care if a buffer is used or not. The maximum size of the input buffer is 32767 bytes.
out_buffer_size (IN)	The size of output buffer. The use of an output buffer can speed up execution performance in sending data to the server. The appropriate size of buffer depends on the flow of data between the client and the server, and the network condition. A 0 value means no buffer should be used. A NULL value means the caller does not care if a buffer is used or not. The maximum size of the output buffer is 32767 bytes.
charset (IN)	The on-the-wire character set. Since text messages in the database may be encoded in a character set that is different from the one expected on the wire (i.e. the character set specified by the communication protocol, or the one stipulated by the other end of the communication), text messages in the database will be converted to and from the on-the-wire character set as they are sent and received on the network using read_text(), read_line(), write_text() and write_line(). Set this parameter to NULL when no conversion is needed.
newline (IN)	The newline character sequence. This newline character sequence is appended to the text line sent by write_line() API.
tx_timeout	A time in seconds that the UTL_TCP package should wait before giving up in a read or write operations in this connection. In read operations, this package gives up if no data is available for reading immediately. In write operations, this package gives up if the output buffer is full and no data is to be sent in the network without being blocked. Zero (0) indicates not to wait at all. NULL indicates to wait forever.

Usage Notes

Note that connections opened by this UTL_TCP package can remain open and be passed from one database call to another in MTS configuration. However, the connection must be closed explicitly. The connection will remain open when the PL/SQL record variable that stores the connection goes out-of-scope in the PL/SQL program. Failing to close unwanted connections may result in unnecessary tying up of local and remote system resources.

The parameters local_host and local_port are ignored currently when open_connection makes a TCP/IP connection. It does not attempt to use the specified local host and port number when the connection is made.

In the current release of the UTL_TCP package, the parameters local_host and local_port are ignored when open_connection makes a TCP/IP connection. It does not attempt to use the specified local host and port number when the connection is made. The local_host and local_port fields will not be set in the connection record returned by the function.

Time-out on write operations is not supported in the current release of the UTL_TCP package.

Related Functions

close_connection(), close_all_connections()