INFORMIXCONTIME session environment option

Use the INFORMIXCONTIME session environment option of the SET ENVIRONMENT statement to set an upper limit on the number of seconds while the current session attempts to establish a connection to another database server, before an error is returned.

The INFORMIXCONTIME session environment option has this syntax:


INFORMIXCONTIME environment option

                                    .-'1'-----------.   
|--SET ENVIRONMENT INFORMIXCONTIME--+-+-----------+-+-----------|
                                      '-'integer'-'

Element	Description	Restrictions	Syntax
integer	An unsigned integer value > `0` sets the maximum number of seconds to attempts to establish a connection to a database server	Must be delimited between single (`'`) or double (`"`) quotation marks. A setting of `'0'` defaults to the setting of the INFORMIXCONTIME configuration parameter.	Literal Number as Quoted String

Usage

Use the INFORMIXCONTIME session environment option of the SET ENVIRONMENT statement to limit the number of seconds to spend attempting to establish a connection to a database server in the current session, before the connection effort times out with an error.

'integer' > 0: This value sets an upper limit on the time spent attempting to establish a connection, including (if the initial attempt fails) at least one additional attempt.

After the time limit that INFORMIXCONTIME specifies has been exceeded, or if no connection with another database server has been established after (integer_R + 1) attempts, for integer_R the INFORMIXCONRETRY setting, the CONNECT statement or the implicit connection fails, and the database server returns an error. By setting the INFORMIXCONTIME and INFORMIXCONRETRY session environment variables to configure your sever-to-server connection capability in the current session, you can minimize connection errors. To estimate the optimal value for INFORMIXCONTIME, take into account the total distance between nodes, the hardware speed, the volume of traffic, and the concurrency level of the network.

Order of precedence for time limits on connections

This is the ascending order of precedence (lowest to highest) among 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 instance:

System default value of 60 seconds, if none of the methods below are set.
INFORMIXCONTIME configuration parameter
INFORMIXCONTIME client environment variable
SET ENVIRONMENT INFORMIXCONTIME statement of SQL.

The INFORMIXCONTIME session environment option can override the setting of the client INFORMIXCONTIME environment variable, or of the INFORMIXCONTIME configuration parameter, or of the system default value, if any of these has established a time limit different from the SET ENVIRONMENT INFORMIXCONTIME value.

Setting session environment options for connections

The value of the INFORMIXCONTIME session environment option is divided by the value of the INFORMIXCONRETRY session environment option to determine the maximum number of seconds between successive connection attempts, if the previous attempt of the same CONNECT statement failed to establish a connection.

For example, the following statements set INFORMIXCONTIME to 60 seconds and INFORMIXCONRETRY to one retry:

SET ENVIRONMENT INFORMIXCONTIME '60';
SET ENVIRONMENT INFORMIXCONRETRY '1';

In this example, the CONNECT statement attempts to establish a connection for 60 seconds. An initial attempt is made to connect to the database server at 0 seconds. If the INFORMIXCONTIME session environment option is set to the default value of '0', an additional attempt to connect is made within 60 seconds, if necessary, before connection failure error -908 is returned.

Similarly, you can configure these session environment options for multiple retries. With the same INFORMIXCONTIME setting, the following statement specifies three additional retries:

SET ENVIRONMENT INFORMIXCONRETRY '3';

If INFORMIXCONRETRY is set to '3', up to three additional attempts to connect to the database server are made (at 20, 40, and 60 seconds, if necessary), before an error is returned.

This 20-second interval is the result of dividing the INFORMIXCONTIME value by the INFORMIXCONRETRY value.

If you set the INFORMIXCONTIME session environment option to '0', as in this example,

SET ENVIRONMENT INFORMIXCONTIME '0';

the database server automatically uses the setting of the INFORMIXCONTIME configuration parameter. If the INFORMIXCONTIME parameter is not set, its default value of 60 seconds is used during subsequent CONNECT statements in the session.

Implicit connections with database statements

If the CONNECT statement does not begin your application, its first SQL statement must either be one of the following database statements, or else be a single-statement prepared object for one of the same statements:

DATABASE
CREATE DATABASE
DROP DATABASE

If one of these statements, rather than the CONNECT statement, is the first SQL statement in an application, that database statement can establishes a connection to a database server that is known as an implicit connection, because no CONNECT statement in the session has established an explicit connection. To establishes the implicit connection, a database statement must specify one of the following, either as an SQL identifier or as the content of a variable:

a database server and a database,
or a database server only,
or a database only.

If the database statement specifies only a database, the database server obtains a database server name from the DBPATH environment variable setting. For more information on establishing implicit connections in UNIX or Windows environments, see the topic Specifying the Database Environment.

If you issue the CONNECT statement after the application establishes an implicit connection with only a database name, the CONNECT statement must search DBPATH to identify the database server for that database. For this search, the INFORMIXCONRETRY session environment option 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 INFORMIXCONTIME value is exceeded. In this context, the CONNECT statement might take longer than the INFORMIXCONTIME time limit to return an error that indicates a connection failure, or indicating that the database was not found.
The INFORMIXCONTIME value is divided among the number of database server entries that are specified in DBPATH. Thus, if DBPATH contains numerous servers, you can use the SET ENVIRONMENT INFORMIXCONTIME statement to increase the INFORMIXCONTIME value accordingly. For example, if DBPATH contains three entries, in order to spend at least 30 seconds attempting each connection, set INFORMIXCONTIME to '90'.
```
SET ENVIRONMENT INFORMIXCONTIME '90';
```