CONNECT_TIMEOUT environment variable

The CONNECT_TIMEOUT environment variable specifies the number of seconds the CONNECT statement attempts to establish a connection to a database server before returning an error. If you set no value, the default of 60 seconds can typically support a few hundred concurrent client connections. However, some systems might encounter few connection errors with a value as low as 15. The total distance between nodes, hardware speed, the volume of traffic, and the concurrency level of the network can all affect what value you should set to optimize CONNECT_TIMEOUT.

The CONNECT_TIMEOUT and CONNECT_RETRIES environment variables let you configure your client-side connection capability to retry the connection instead of returning a -908 error.

seconds: Represents the minimum number of seconds spent in attempts to establish a connection to a database server.

For example, enter this command to set CONNECT_TIMEOUT to 60 seconds:

setenv CONNECT_TIMEOUT 60

If CONNECT_TIMEOUT is set to 60 and CONNECT_RETRIES is set to 3, attempts to connect to the database server (after the initial attempt at 0 seconds) are made at 20, 40, and 60 seconds, if necessary, before aborting. This 20-second interval is the result of CONNECT_TIMEOUT divided by CONNECT_RETRIES. If you set the CONNECT_TIMEOUT value to zero, the database server automatically uses the default value of 60 seconds.

If the CONNECT statement must search DBPATH, the CONNECT_RETRIES setting specifies the number of additional connection attempts that can be made for each database server entry in DBPATH.

All appropriate servers in the DBPATH setting are accessed at least once, even if the CONNECT_TIMEOUT value is exceeded. Thus, the CONNECT statement might take longer than the CONNECT_TIMEOUT time limit to return an error that indicates connection failure or that the database was not found.
The CONNECT_TIMEOUT value is divided among the number of database server entries that are specified in DBPATH. Thus, if DBPATH contains numerous servers, increase the CONNECT_TIMEOUT value accordingly. For example, if DBPATH contains three entries, to spend at least 30 seconds attempting each connection, set CONNECT_TIMEOUT to 90.

The CONNECT_TIMEOUT and CONNECT_RETRIES environment variables can be modified with the onutil SET command, as in the following example:

% onutil
1> SET CONNECT_TIMEOUT 120;
Dynamic Configuration completed successfully
2> SET CONNECT_RETRIES 10;
Dynamic Configuration completed successfully

Order of precedence among CONNECT_TIMEOUT settings

When you specify a setting for the CONNECT_TIMEOUT client environment variable, it overrides the CONNECT_TIMEOUT configuration parameter settings in the onconfig file for the current session.

If the SET ENVIRONMENT statement specifies a setting for the CONNECT_RETRIES session environment option, however, the SQL statement setting overrides the CONNECT_RETRIES client environment variable setting for subsequent connection attempts during the current session. The SET ENVIRONMENT CONNECT_RETRIES setting has no effect on other sessions.

In summary, this is the ascending order (lowest to highest) of the methods for setting an upper limit on the amount of time that a CONNECT statement can spend attempting to connect to a database server:

CONNECT_TIMEOUT configuration parameter
CONNECT_TIMEOUT client environment variable
SET ENVIRONMENT CONNECT_TIMEOUT statement of SQL.

CONNECT_TIMEOUT takes precedence over the CONNECT_RETRIES setting. Connection attempts can end after the CONNECT_TIMEOUT value is exceeded, but before the CONNECT_RETRIES value is reached.