Commit 617a6429 authored by Kubo Takehiro's avatar Kubo Takehiro
Browse files

Rename outbound_connect_timeout in OCI8::properties to connect_timeout.

parent a9ac6bbd
2016-01-29 Kubo Takehiro <kubo@jiubao.org>
* lib/oci8/oci8.rb, lib/oci8/properties.rb: Rename outbound_connect_timeout in
OCI8::properties to connect_timeout.
* docs/timeout-parameters.md: Revise document.
2015-12-20 Kubo Takehiro <kubo@jiubao.org>
* lib/oci8/cursor.rb: Use OCI_ATTR_UB8_ROW_COUNT to get the number of processed rows
if Oracle client version is 12c or upper.
......
......@@ -6,37 +6,72 @@ Timeout Parameters
The following timeout parameters are available since ruby-oci8 2.2.2.
* tcp_connect_timeout
* outbound_connect_timeout
* connect_timeout
* send_timeout
* recv_timeout
For example:
OCI8.properties[:tcp_connect_timeout] = 10
OCI8.properties[:outbound_connect_timeout] = 15
OCI8.properties[:connect_timeout] = 15
OCI8.properties[:send_timeout] = 60
OCI8.properties[:recv_timeout] = 60
These parameters are equivalent to [TCP.CONNECT_TIMEOUT][], [SQLNET.OUTBOUND_CONNECT_TIMEOUT][],
[SQLNET.SEND_TIMEOUT][] and [SQLNET.RECV_TIMEOUT][] respectively in client-side `sqlnet.ora`.
They affect only TCP connections.
These parameters are applied only to TCP/IP connections.
The first two parameters `tcp_connect_timeout` and `outbound_connect_timeout`
The first two parameters `tcp_connect_timeout` and `connect_timeout`
are applied only to [connect descriptors][connect descriptor] using [Easy Connect Naming Method][EZCONNECT].
If you use easy connect naming method without any of `port`, `service_name`, `server` and `instance_name`,
you need to use `//host` to distinguish it from a net service name in `tnsnames.ora`. If you need
these parameters without using easy connect naming, add equivalent parameters [CONNECT_TIMEOUT][]
and/or [TRANSPORT_CONNECT_TIMEOUT][] in your `tnsname.ora` instead.
you need to use `//host` to distinguish it from a net service name in `tnsnames.ora`.
The next two parameters `send_timeout` and `recv_timeout` are available on Oracle 11g client
or upper. These parameters can be changed by {OCI8#send_timeout=} and/or {OCI8#recv_timeout=}
after establishing a connection.
Note that establishing a connection consists of two phases. The first phase is connecting
to a service. The second phase is user authentication. The first two parameters
`tcp_connect_timeout` and `outbound_connect_timeout` affect only the first phase.
The next two parameters `send_timeout` and `recv_timeout` affect network round trips
since the second phase.
or upper.
tcp_connect_timeout
-------------------
`tcp_connect_timeout` is equivalent to [TCP.CONNECT_TIMEOUT][] in the client-side `sqlnet.ora` and
[TRANSPORT_CONNECT_TIMEOUT][] in the address descriptor.
See description about [TCP.CONNECT_TIMEOUT][] and [TRANSPORT_CONNECT_TIMEOUT][].
connect_timeout
---------------
`connect_timeout` is equivalent to [SQLNET.OUTBOUND_CONNECT_TIMEOUT][] in the client-side `sqlnet.ora`
and [CONNECT_TIMEOUT][] in the address description.
See description about [SQLNET.OUTBOUND_CONNECT_TIMEOUT][] and [CONNECT_TIMEOUT][].
Note: this parameter isn't equivalent to login timeout. It need the following three
steps to establish a database connection.
1. Establish a TCP/IP connection.
2. Establish an Oracle Net connection.
3. Authenticate and authorize the database user.
`tcp_connect_timeout` sets the timeout of the first step.
`connect_timeout` sets the total timeout of the first and the second steps.
There is no timeout parameter to limit the maximum time of all three steps.
Use `send_timeout` and `recv_timeout` in case that a TCP/IP connection stalls
in the third step.
send_timeout
------------
`send_timeout` is equivalent to [SQLNET.SEND_TIMEOUT][] in the client-side `sqlnet.ora`.
See description about [SQLNET.SEND_TIMEOUT][].
See also {OCI8#send_timeout=}.
recv_timeout
------------
`recv_timeout` is equivalent to [SQLNET.RECV_TIMEOUT][] in the client-side `sqlnet.ora`.
See description about [SQLNET.RECV_TIMEOUT][].
See also {OCI8#recv_timeout=}.
Note: This parameter must be larger than the longest SQL execution time in your applications.
[TCP.CONNECT_TIMEOUT]: http://docs.oracle.com/database/121/NETRF/sqlnet.htm#BIIDDACA
[SQLNET.OUTBOUND_CONNECT_TIMEOUT]: https://docs.oracle.com/database/121/NETRF/sqlnet.htm#NETRF427
......
......@@ -116,9 +116,9 @@ class OCI8
attach_mode |= 0x0200 # OCI_CPOOL and OCI_LOGON2_CPOOL
else
tcp_connect_timeout = OCI8::properties[:tcp_connect_timeout]
outbound_connect_timeout = OCI8::properties[:outbound_connect_timeout]
if tcp_connect_timeout || outbound_connect_timeout
dbname = to_connect_descriptor(dbname, tcp_connect_timeout, outbound_connect_timeout)
connect_timeout = OCI8::properties[:connect_timeout]
if tcp_connect_timeout || connect_timeout
dbname = to_connect_descriptor(dbname, tcp_connect_timeout, connect_timeout)
end
end
if stmt_cache_size
......@@ -500,7 +500,7 @@ class OCI8
# and add TRANSPORT_CONNECT_TIMEOUT or CONNECT_TIMEOUT.
#
# @private
def to_connect_descriptor(database, tcp_connect_timeout, outbound_connect_timeout)
def to_connect_descriptor(database, tcp_connect_timeout, connect_timeout)
if @@easy_connect_naming_regex =~ database && ($1 || $2 || $4 || $5 || $6 || $7)
connect_data = []
connect_data << "(SERVICE_NAME=#$5)"
......@@ -512,8 +512,8 @@ class OCI8
if tcp_connect_timeout
desc << "(TRANSPORT_CONNECT_TIMEOUT=#{tcp_connect_timeout})"
end
if outbound_connect_timeout
desc << "(CONNECT_TIMEOUT=#{outbound_connect_timeout})"
if connect_timeout
desc << "(CONNECT_TIMEOUT=#{connect_timeout})"
end
"(DESCRIPTION=#{desc.join})"
else
......
......@@ -14,7 +14,7 @@ class OCI8
:events_mode => ((OCI8.__get_prop(2) & 4) != 0), # 4 <- OCI_EVENTS in oci.h
:cancel_read_at_exit => false,
:tcp_connect_timeout => nil,
:outbound_connect_timeout => nil,
:connect_timeout => nil,
:send_timeout => nil,
:recv_timeout => nil,
}
......@@ -57,7 +57,7 @@ class OCI8
when :cancel_read_at_exit
val = val ? true : false
OCI8.__set_prop(3, val)
when :tcp_connect_timeout, :outbound_connect_timeout, :send_timeout, :recv_timeout
when :tcp_connect_timeout, :connect_timeout, :send_timeout, :recv_timeout
if !val.nil?
val = val.to_i
raise ArgumentError, "The property value for :#{name} must be nil or a positive integer." if val <= 0
......@@ -147,7 +147,7 @@ class OCI8
#
# *Since:* 2.2.2
#
# [:outbound_connect_timeout]
# [:connect_timeout]
#
# See {file:docs/timeout-parameters.md}
#
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment