The following sections describe how to configure and use the Oracle Type 4 JDBC Informix driver:
The driver classes for the Oracle Type 4 JDBC Informix driver are:
XA: weblogic.jdbcx.informix.InformixDataSource Non-XA: weblogic.jdbc.informix.InformixDriver
Use these driver classes when configuring a JDBC data source in your WebLogic Server domain.
To connect to an Informix database, use the following URL format:
jdbc:weblogic:informix://hostname:port[;property=value[;...]]
where:
hostname is the TCP/IP address or TCP/IP host name of the server to which you are connecting. See Using IP Addresses for details on using IP addresses.
Note:
Untrusted applets cannot open a socket to a machine other than the originating host.port is the number of the TCP/IP port.
property=value specifies connection properties. For a list of connection properties and their valid values, see Informix Connection Properties.
For example:
jdbc:weblogic:informix://server4:1526;informixServer=ol_test; DatabaseName=ACCT01;User=test;Password=secret
Table 4-1 lists the JDBC connection properties supported by the Informix driver, and describes each property. You can use these connection properties in a JDBC data source configuration in your WebLogic Server domain. To specify a property, use the following form in the JDBC data source configuration: property=value.
Note:
All connection property names are case-insensitive. For example, Password is the same as password.Required properties are noted as such. The data type listed for each connection property is the Java data type used for the property value in a JDBC data source.Table 4-1 Informix Connection String Properties
| Property | Description |
|---|---|
|
AccountingInfo |
Accounting information to be stored in the database. This value is stored locally and is used for database administration/monitoring purposes Data type: string Valid Values: |
|
AlternateServers |
A list of alternate database servers that is used to failover new or lost connections, depending on the failover method selected. See the FailoverMode property for information about choosing a failover method. Data type: String Valid Values:
The server name ( Example: The following URL contains alternate server entries for server2 and server3. The alternate server entries contain the optional
Default: None |
|
ApplicationName |
The name of the application to be stored in the database. Thisvalue is stored locally and is used for database administration/value is stored locally and is used for database administration/monitoring purposes. Data Type: String Valid Values: |
|
ClientHostName |
The host name of the client machine to be stored in the database. This value is stored locally and is used for database administration/monitoring purposes. Data Type: String Valid Values: |
|
ClientUser |
The user ID to be stored in the database. This value is stored locally and is used for database administration/monitoring purposes. Data Type: String Valid Values: |
|
CodePageOverride |
The code page to be used by the driver to convert Character data. The specified code page overrides the default database code page or column collation. All Character data that is returned from or written to the database is converted using the specified code page. By default, the driver automatically determines which code page to use to convert Character data. Use this property only if you need to change the driver's default behavior. For example: CP950. Data Type: String Valid Values: |
|
ConnectionRetryCount |
The number of times the driver retries connection attempts to the primary database server, and if specified, alternate servers until a successful connection is established. If an application sets a login timeout value (for example, using DataSource.loginTimeout or DriverManager.loginTimeout), and the login timeout expires, the driver ceases connection attempts. Data Type: Int Valid values: 0 | If set to 0, the driver does not try to reconnect after the initial unsuccessful attempt. If set to For example: If this property is set to 2 and alternate servers are specified using the |
|
ConnectionRetryDelay |
The number of seconds the driver waits between connection retry attempts when For example: If Data Type: Int Valid values: 0 | |
|
ConvertNull |
Controls how data conversions are handled for null values. Data Type: Int Valid values: 0 | 1. The default is 1. If set to 1, the driver checks the data type being requested against the data type of the table column storing the data. If a conversion between the requested type and column type is not defined, the driver generates an "unsupported data conversion" exception regardless of the data type of the column value. If set to 0, the driver does not perform the data type check if the value of the column is null. This allows null values to be returned even though a conversion between the requested type and the column type is undefined. |
|
Database |
An alias for the |
|
DatabaseName |
The name of the database to which you want to connect. If this property is not specified, a connection is established to the specified server without connecting to a particular database. A connection that is established to the server without connecting to the database allows an application to use CREATE DATABASE and DROP DATABASE SQL statements. These statements require that the driver cannot be connected to a database. An application can connect to the database after the connection is established by executing the DATABASE SQL statement. Refer to your IBM Informix documentation for details on using the CREATE DATABASE, DROP DATABASE, and DATABASE SQL statements. Data Type: String Valid values: Alias
|
|
DBDate |
Sets the Informix DBDate server option for formatting literal date values when inserting, updating, and retrieving data in DATE columns. Using this property, you can customize the following items:
Data Type: String Valid values are: DMY2, DMY4, MDY2, MDY4, Y4DM, Y4MD, Y2DM, and Y4MD where D is a 2-digit day field, M is a 2-digit month field, Y2 is a 2-digit year field, and Y4 is a 4-digit year field. If unspecified, the format of literal date values conforms to the default server behavior. Optionally, a separator character may be specified as the last character of the value. Valid separator characters are the hyphen (-), a period (.), and a forward slash (/). If a separator is not specified, a forward slash (/) is used to separate the fields. For example, a value of Y4MD- specifies a date format that has a 4-digit year, followed by the month and then by the day. The date fields are separated by a hyphen (-). For example: 2004-02-15. This property does not affect the format of the string in the date escape syntax. Dates specified using the date escape syntax always use the JDBC escape format yyyy-mm-dd. |
|
FailoverGranularity |
Determines whether the driver fails the entire failover process or continues with the process if exceptions occur while trying to reestablish a lost connection. This property is ignored if Data Type: String Valid Values: If set to If set to If set to If set to Default is |
|
FailoverMode |
Specifies the type of failover method the driver uses. Data Type: String Valid Values If set to If set to If set to Note the following:
Default is |
|
FailoverPreconnect |
Specifies whether the driver tries to connect to the primary and an alternate server at the same time. This property is ignored if Data Type: boolean Valid Values: If set to If set to The Default is |
|
FetchBufferSize |
Specifies the size (in bytes) of the fetch buffer that the driver uses when retrieving data from the database. Valid values are any positive integer from 1 to 32767. Decreasing the fetch buffer size reduces memory consumption, but means more network round trips, which decreases performance. Increasing the fetch buffer size improves performance because fewer network round trips are needed to return data from the database. To determine the optimal value, use the following formula: where A is the number of rows your application returns when executing Select statements and B is the number of row columns typically returned when executing Select statements. See Performance Considerations for information about configuring this property for optimal performance. The default is 32767 |
|
ImportStatementPool |
Specifies the path and file name of the file to be used to load the contents of the statement pool. When this property is specified, statements are imported into the statement pool from the specified file. If the driver cannot locate the specified file when establishing the connection, the connection fails and the driver throws an exception. Data Type: String Valid Values: |
|
InformixServer (REQUIRED) |
The name of the Informix database server to which you want to connect. Data Type: String Valid Values: |
|
InitializationString |
Specifies one or multiple SQL commands to be executed by the driver after it has established the connection to the database and has performed all initialization for the connection. For example: Multiple commands must be separated by semicolons. In addition, if this property is specified in a connection URL, the entire value must be enclosed in parentheses when multiple commands are specified. For example: jdbc:weblogic:informix://server1:2003; InformixServer=TestServer;DatabaseName=Test; InitializationString=(command1;command2) If the execution of a SQL command fails, the connection attempt also fails and the driver throws an exception indicating which SQL command or commands failed. Data Type: String Default: None |
|
InsensitiveResultSetBufferSize |
-1, zero (0), or x. Determines the amount of memory used by the driver to cache insensitive result set data. If set to -1, the driver caches all insensitive result set data in memory. If the size of the result set exceeds available memory, an If set to 0, the driver caches all insensitive result set data in memory, up to a maximum of 2 GB. If the size of the result set data exceeds available memory, the driver pages the result set data to disk. Because result set data may be written to disk, the driver may have to reformat the data to write it correctly to disk. If set to x, where x is a positive integer, the driver caches all insensitive result set data in memory, using this value to set the size (in KB) of the memory buffer for caching insensitive result set data. If the size of the result set data exceeds the buffer size, the driver pages the result set data to disk. Because the result set data may be written to disk, the driver may have to reformat the data to write it correctly to disk. Specifying a buffer size that is a power of 2 results in more efficient memory use. Data Type: int The default is 2048 (KB) |
|
JavaDoubleToString |
True or false. Determines whether the driver uses its internal conversion algorithm or the JVM conversion algorithm when converting double or float values to string values. If set to true, the driver uses the JVM algorithm when converting double or float values to string values. If set to false (the default), the driver uses its internal algorithm when converting double or float values to string values. Setting the property to false improves performance; however, slight rounding differences can occur when compared to the same conversion using the JVM algorithm. These differences are within the allowable error of the double and float data types. The default is false. |
|
JavaDoubleToString |
Determines which algorithm the driver uses when converting a double or float value to a string value. By default, the driver uses its own internal conversion algorithm, which improves performance. Data Type: boolean Valid Values: If If |
|
JDBCBehavior |
Determines how the driver describes database data types that map to the following JDBC 4.0 data types: This property is applicable only when the application is using Java SE 6. Data Type: int Valid Values: 0 | 1 If 0, the driver describes the data types as JDBC 4.0 data types when using Java SE 6. If 1, the driver describes the data types using JDBC 3.0-equivalent data types, regardless of JVM. This allows your application to continue using JDBC 3.0 types in a Java SE 6 environment. The default value is 1. |
|
LoadBalancing |
Determines whether the driver uses client load balancing in its attempts to connect to the database servers (primary and alternate). You can specify one or multiple alternate servers by setting the AlternateServers property. Data Type: boolean Valid Values: If If |
|
LoginTimeout |
The amount of time, in seconds, the driver waits for a connection to be established before returning control to the application and throwing a timeout exception. Data Type: int Valid Values: 0 | If 0, the driver does not time out a connection request. The default value is 0. If |
|
MaxPooledStatements |
The maximum number of pooled prepared statements for this connection. Setting MaxPooledStatements to an integer greater than zero (0) enables the driver's internal prepared statement pooling, which is useful when the driver is not running from within an application server or another application that provides its own prepared statement pooling.Data Type: int Valid Values: 0 | If set to 0, the driver's internal prepared statement pooling is not enabled. The default value is 0. If set to Example: If the value of this property is set to 20, the driver caches the last 20 prepared statements that are created by the application. |
|
MaxStatements |
An alias for the |
|
Password (REQUIRED) |
A password that is used to connect to your Informix database. A password is required if security is enabled on your database. Contact your system administrator to obtain your password. Data Type: String Valid Values: string where string is a valid password. The password is case-sensitive. The default value is null (no password). |
|
PortNumber (REQUIRED) |
The TCP port on which the database server listens for connections. The default varies depending on operating system. This property is supported only for data source connections. |
|
ProgramID |
The product and version information of the driver on the client to be stored in the database. This value is stored locally and is used for database administration/monitoring purposes. Data Type: String Valid Values: DDJVVRRM where:
Example: DDJ04100 |
|
QueryTimeout |
Positive integer, -1, or zero (0). Sets the default query timeout (in seconds) for all statements created by a connection. If set to a positive integer, the driver uses the value as the default timeout for any statement created by the connection. To override the default timeout value set by this connection option, call the If set to -1, the query timeout functionality is disabled. The driver silently ignores calls to the If set to 0 (the default), the default query timeout is infinite (the query does not time out). |
|
ResultSetMetaDataOptions |
Zero (0) or 1. The Informix driver can return table name information in the If set to 0 (the default) and the If set to 1 and the See Performance Considerations for information about configuring this property for optimal performance. The default is 0. |
|
ServerName (REQUIRED) |
Specifies either the IP address in IPv4 or IPv6, or the server name (if your network supports named servers) of the primary database server. For example, 122.23.15.12 or InformixServer. This property is supported only for data source connections. Data Type: String |
|
SpyAttributes |
Enables Spy to log detailed information about calls issued by the driver on behalf of the application. Data Type: String Default is not enabled. See "Tracking JDBC Calls with WebLogic JDBC Spy" for more details. |
|
UseDelimitedIdentifier |
Controls how the Informix server interprets double quote (") characters in SQL statements. Data Type: boolean If set to If set to Note: If the The default is |
|
User (REQUIRED) |
The case-insensitive default user name used to connect to the Informix database. A user name is required only if security is enabled on your database. If so, contact your system administrator to obtain your user name. Data Type: String Default value is None. |
If anything causes a change to a database table or procedure, such as adding an index, or recompiling the procedure, all existing JDBC PreparedStatements that access it must be re-prepared before they can be used again. This is a limitation of the Informix database management system. WebLogic Server caches, retains, and reuses application PreparedStatements along with pooled connections, so if your application uses prepared statements that access tables or procedures that are dropped and recreated or for which the definition is changed, re-execution of a cached prepared statement will fail once. WebLogic Server will then remove the defunct prepared statement from the cache and replace it when the application asks for the statement again.
To avoid any PreparedStatement failure due to table or procedure changes in the DBMS while WebLogic Server is running, set the Statement Cache Size to 0. WebLogic will make a new PreparedStatement for each request. However, with the statement cache disabled, you will lose the performance benefit of statement caching.
For information about setting the Statement Cache Size, see "Increasing Performance with the Statement Cache" in Configuring and Managing JDBC Data Sources for Oracle WebLogic Server.
Setting the following connection properties for the Informix driver as described in the following list can improve performance for your applications:
Decreasing the fetch buffer size reduces memory consumption, but means more network round trips, which decreases performance. Increasing the fetch buffer size improves performance because fewer network round trips are needed to return data from the database. To determine the optimal value, use the formula X = A * B * 50, where A is the number of rows your application returns when executing Select statements and B is the number of row columns typically returned when executing Select statements.
To improve performance when using scroll-insensitive result sets, the driver can cache the result set data in memory instead of writing it to disk. By default, the driver caches 2 MB of insensitive result set data in memory and writes any remaining result set data to disk. Performance can be improved by increasing the amount of memory used by the driver before writing data to disk or by forcing the driver to never write insensitive result set data to disk. The maximum cache size setting is 2 GB.
To improve performance, the driver's own internal prepared statement pooling should be enabled when the driver does not run from within an application server or from within another application that does not provide its own prepared statement pooling. When the driver's internal prepared statement pooling is enabled, the driver caches a certain number of prepared statements created by an application. For example, if the MaxPooledStatements property is set to 20, the driver caches the last 20 prepared statements created by the application. If the value set for this property is greater than the number of prepared statements used by the application, all prepared statements are cached.
By default, the Informix driver skips the additional processing required to return the correct table name for each column in the result set when the ResultSetMetaData.getTableName() method is called. Because of this, the getTableName() method may return an empty string for each column in the result set. If you know that your application does not require table name information, this setting provides the best performance.
Table 4-2 lists the data types supported by the Informix driver and how they are mapped to the JDBC data types.
| Informix Data Type | JDBC Data Type |
|---|---|
|
BLOB |
BLOB |
|
BOOLEAN |
BIT |
|
BYTE |
LONGVARBINARY |
|
CHAR |
CHAR |
|
CLOB |
CLOB |
|
DATE |
DATE |
|
DATETIME HOUR TO SECOND |
TIME |
|
DATETIME YEAR TO DAY |
DATE |
|
DATETIME YEAR TO FRACTION(5) |
TIMESTAMP |
|
DATETIME YEAR TO SECOND |
TIMESTAMP |
|
DECIMAL |
DECIMAL |
|
FLOAT |
FLOAT |
|
INT8 |
BIGINT |
|
INTEGER |
INTEGER |
|
LVARCHAR |
VARCHAR |
|
MONEY |
DECIMAL |
|
NCHAR |
CHAR If |
|
NVARCHAR |
VARCHAR If |
|
SERIAL |
INTEGER |
|
SERIAL8 |
BIGINT |
|
SMALLFLOAT |
REAL |
|
SMALLINT |
SMALLINT |
|
TEXT |
LONGVARCHAR |
|
VARCHAR |
VARCHAR |
See Appendix B, "GetTypeInfo" for more information about data types.
The Informix driver allows applications to store and return the following types of client information associated with a particular connection:
Name of the application
User ID
Host name of the client
Additional accounting information, such as an accounting ID
Product name and version of the Informix driver
This information can be used for database administration and monitoring purposes. See Appendix C “Client In.
See Appendix C, "SQL Escape Sequences for JDBC" for information about the SQL escape sequences supported by the Informix driver.
Informix supports the Read Committed, Read Uncommitted, Repeatable Read, and Serializable isolation levels. The default is Read Committed.
The Informix driver supports scroll-sensitive result sets, scroll-insensitive result sets, and updatable result sets.
Note:
When the Informix driver cannot support the requested result set type or concurrency, it automatically downgrades the cursor and generates one or more SQLWarnings with detailed information.The Informix driver supports returning parameter metadata as described in this section.
The Informix driver supports returning parameter metadata for Insert and Update statements.
The Informix driver supports returning parameter metadata for Select statements that contain parameters in ANSI SQL 92 entry-level predicates, for example, such as COMPARISON, BETWEEN, IN, LIKE, and EXISTS predicate constructs. Refer to the ANSI SQL reference for detailed syntax.
Parameter metadata can be returned for a Select statement if one of the following conditions is true:
The statement contains a predicate value expression that can be targeted against the source tables in the associated FROM clause. For example:
SELECT * FROM foo WHERE bar > ?
In this case, the value expression "bar" can be targeted against the table "foo" to determine the appropriate metadata for the parameter.
The statement contains a predicate value expression part that is a nested query. The nested query's metadata must describe a single column. For example:
SELECT * FROM foo WHERE (SELECT x FROM y WHERE z = 1) < ?
The following Select statements show further examples for which parameter metadata can be returned:
SELECT col1, col2 FROM foo WHERE col1 = ? and col2 > ? SELECT ... WHERE colname = (SELECT col2 FROM t2 WHERE col3 = ?) SELECT ... WHERE colname LIKE ? SELECT ... WHERE colname BETWEEN ? and ? SELECT ... WHERE colname IN (?, ?, ?) SELECT ... WHERE EXISTS(SELECT ... FROM T2 WHERE col1 < ?)
ANSI SQL 92 entry-level predicates in a WHERE clause containing GROUP BY, HAVING, or ORDER BY statements are supported. For example:
SELECT * FROM t1 WHERE col = ? ORDER BY 1
Joins are supported. For example:
SELECT * FROM t1,t2 WHERE t1.col1 = ?
Fully qualified names and aliases are supported. For example:
SELECT a, b, c, d FROM T1 AS A, T2 AS B WHERE A.a = ? and B.b = ?"
When parameter metadata is requested for a column defined as an approximate numeric data type, the driver returns a scale of 255, which indicates the column has an approximate numeric data type and has no scale. For example, suppose we create a table where col2 is an approximate numeric data type with a precision of 20:
CREATE table fooTest(col1 int, col2 decimal(20))
The driver returns parameter metadata that indicates that col2 has a data type of decimal, a precision of 20, and a scale of 255.
If your application requires table name information, the Informix driver can return table name information in ResultSet metadata for Select statements. By setting the ResultSetMetaDataOptions property to 1, the Informix driver performs additional processing to determine the correct table name for each column in the result set when the ResultSetMetaData.getTableName() method is called. Otherwise, the getTableNames() method may return an empty string for each column in the result set.
The table name information that is returned by the Informix driver depends on whether the column in a result set maps to a column in a table in the database. For each column in a result set that maps to a column in a table in the database, the Informix driver returns the table name associated with that column. For columns in a result set that do not map to a column in a table (for example, aggregates and literals), the Informix driver returns an empty string.
The Select statements for which ResultSet metadata is returned may contain aliases, joins, and fully qualified names. The following queries are examples of Select statements for which the ResultSetMetaData.getTableName() method returns the correct table name for columns in the Select list:
SELECT id, name FROM Employee SELECT E.id, E.name FROM Employee E SELECT E.id, E.name AS EmployeeName FROM Employee E SELECT E.id, E.name, I.location, I.phone FROM Employee E, EmployeeInfo I WHERE E.id = I.id SELECT id, name, location, phone FROM Employee, EmployeeInfo WHERE id = empId SELECT Employee.id, Employee.name, EmployeeInfo.location, EmployeeInfo.phone FROM Employee, EmployeeInfo WHERE Employee.id = EmployeeInfo.id
The table name returned by the driver for generated columns is an empty string. The following query is an example of a Select statement that returns a result set that contains a generated column (the column named "upper").
SELECT E.id, E.name as EmployeeName, {fn UCASE(E.name)}
AS upper FROM Employee E
The Informix driver also can return schema name and catalog name information when the ResultSetMetaData.getSchemaName() and ResultSetMetaData.getCatalogName() methods are called if the driver can determine that information. For example, for the following statement, the Informix driver returns "test" for the catalog name, "test1" for the schema name, and "foo" for the table name:
SELECT * FROM test.test1.foo
The additional processing required to return table name, schema name, and catalog name information is only performed if the ResultSetMetaData.getTableName(), ResultSetMetaData.getSchemaName(), or ResultSetMetaData.getCatalogName() methods are called.
The Informix driver supports any JSR 114 implementation of the RowSet interface, including:
CachedRowSets
FilteredRowSets
WebRowSets
JoinRowSets
JDBCRowSets
J2SE 1.4 or higher is required to use rowsets with the driver.
See http://www.jcp.org/en/jsr/detail?id=114 for more information about JSR 114.
When searching a Clob value for a string pattern using the Clob.position method, the search pattern must be less than or equal to a maximum value of 4096 bytes. Similarly, when searching a Blob value for a byte pattern using the Blob.position method, the search pattern must be less than or equal to a maximum value of 4096 bytes.
The Informix driver supports retrieving the values of auto-generated keys. An auto-generated key returned by the Informix driver is the value of a SERIAL column or a SERIAL8 column.
An application can return values of auto-generated keys when it executes an Insert statement. How you return these values depends on whether you are using an Insert statement that contains parameters:
When using an Insert statement that contains no parameters, the Informix driver supports the following form of the Statement.execute() and Statement.executeUpdate() methods to instruct the driver to return values of auto-generated keys:
Statement.execute(String sql, int autoGeneratedKeys)
Statement.execute(String sql, int[] columnIndexes)
Statement.execute(String sql, String[] columnNames)
Statement.executeUpdate(String sql, int autoGeneratedKeys)
Statement.executeUpdate(String sql, int[] columnIndexes)
Statement.executeUpdate(String sql, String[] columnNames)
When using an Insert statement that contains parameters, the Informix driver supports the following form of the Connection.prepareStatement() method to instruct the driver to return values of auto-generated keys:
Connection.prepareStatement(String sql, int autoGeneratedKeys)
Connection.prepareStatement(String sql, int[] columnIndexes)
Connection.prepareStatement(String sql, String[] columnNames)
An application can retrieve values of auto-generated keys using the Statement.getGeneratedKeys() method. This method returns a ResultSet object with a column for each auto-generated key.
Use the following procedure to configure failover:
Specify the primary and alternate servers:
Specify your primary server using a connection URL or data source.
Specify one or multiple alternate servers by setting the AlternateServers property.
See rss
Choose a failover method by setting the FailoverMode connection property. The default method is connection failover (FailoverMode=connect).
If FailoverMode=extended or FailoverMode=select, set the FailoverGranularity property to specify how you want the driver to behave if exceptions occur while trying to reestablish a lost connection. The default behavior of the driver is to continue with the failover process and post any exceptions on the statement on which they occur (FailoverGranularity=nonAtomic).
Optionally, configure the connection retry feature. See �gSpecifying Connection Retry�h on page 214.
Optionally, set the FailoverPreconnect property if you want the driver to establish a connection with the primary and an alternate server at the same time. The default behavior is to connect to an alternate server only when failover is caused by an unsuccessful connection attempt or a lost connection (FailoverPreconnect=false).
Connection information for primary and alternate servers can be specified using either one of the following methods:
Connection URL through the JDBC Driver Manager
JDBC data source
For example, the following connection URL for the Informix driver specifies connection information for the primary and alternate servers using a connection URL:
jdbc:datadirect:informix://server1:2003;InformixServer=TestServer; DatabaseName=TestServer;User=test;Password=secret; AlternateServers=(server2:2003;InformixServer=TestServer2,server3:2003)
In this example:
...server1:2003;InformixServer=TestServer; DatabaseName=TestServer...
is the part of the connection URL that specifies connection information for the primary server. Alternate servers are specified using the AlternateServers property. For example:
...;AlternateServers=(server2:2003;InformixServer=TestServer2,server3:2003)
Similarly, the same connection information for primary and alternate servers specified using a JDBC data source would look like this:
InformixDataSource mds = new InformixDataSource();
mds.setDescription("My InformixDataSource");
mds.setServerName("server1");
mds.setPortNumber(2003);
mds.setInformixServer("TestServer");
mds.setDatabaseName("TestServer");
mds.setUser("test");
mds.setPassword("secret");
mds.setAlternateServers=(server2:2003;InformixServer= TestServer2,server3:2003)
In this example, connection information for the primary server is specified using the ServerName, PortNumber, InformixServer, and DatabaseName properties. Connection information for alternate servers is specified using the AlternateServers property.
The value of the AlternateServers property is a string that has the format:
(servername1[:port1][;property=value[;...]][,servername2[:port2] [;property=value[;...]]]...)
where:
servername1 is the IP address or server name of the first alternate database server, servername2 is the IP address or server name of the second alternate database server, and so on. The IP address or server name is required for each alternate server entry.
port1 is the port number on which the first alternate database server is listening, port2 is the port number on which the second alternate database server is listening, and so on. The port number is optional for each alternate server entry. If unspecified, the port number specified for the primary server is used.
property=value is either of the following connection properties: DatabaseName or InformixServer. These connection properties are optional for each alternate server entry. For example:
If you do not specify an optional connection property in an alternate server entry, the connection to that alternate server uses the property specified in the URL. For example, if you specify InformixServer=TestServer and DatabaseName=TestServer for the primary server, but do not specify the InformixServer and DatabaseName properties in the alternate server entry as shown in the following URL, the driver uses the InformixServer and DatabaseName specified for the primary server and tries to connect to the TestServer database on the Informix server TestServer:
jdbc:datadirect:informix://server1:2003;InformixServer=TestServer; DatabaseName=TestServer;User=test;Password=secret; AlternateServers=(server2:2003;InformixServer=TestServer2; DatabaseName=TestServer,server3:2003)
Connection retry allows the Informix driver to retry connections to the primary database server, and if specified, alternate servers until a successful connection is established. You use the ConnectionRetryCount and ConnectionRetryDelay properties to enable and control how connection retry works. For example:
jdbc:datadirect:informix://server1:2003;InformixServer=TestServer; DatabaseName=TestServer;User=test;Password=secret; AlternateServers=(server2:2003;DatabaseName=TEST2,server3:2003; DatabaseName=TEST3);ConnectionRetryCount=2;ConnectionRetryDelay=5
In this example, if a successful connection is not established on the Informix driver's first pass through the list of database servers (primary and alternate), the driver retries the list of servers in the same sequence twice (ConnectionRetryCount=2). Because the connection retry delay has been set to five seconds (ConnectionRetryDelay=5), the driver waits five seconds between retry passes.
The following table summarizes the connection properties that control how failover works with the Informix driver.
Table 4-3 Summary: Failover Properties for the Informix Driver
|
AlternateServers |
One or multiple alternate database servers. An IP address or server name identifying each server is required. Port number and supported connection properties (DatabaseName and InformixServer) are optional. If the port number is unspecified, the port specified for the primary server is used. |
|---|---|
|
ConnectionRetryCount |
Number of times the driver retries the primary database server, and if specified, alternate servers until a successful connection is established. The default is 5. |
|
ConnectionRetryDelay |
Wait interval, in seconds, between connection retry attempts when the ConnectionRetryCount property is set to a positive integer. The default is 1. |
|
DatabaseName |
Name of the Informix database to which you want to connect. |
|
FailoverGranularity |
Determines whether the driver fails the entire failover process or continues with the process if exceptions occur while trying to reestablish a lost connection. The default is nonAtomic (the driver continues with the failover process and posts any exceptions on the statement on which they occur). |
|
FailoverMode |
The failover method you want the driver to use. The default is connect (connection failover is used). |
|
FailoverPreconnect |
Specifies whether the driver tries to connect to the primary and an alternate server at the same time. The default is false (the driver tries to connect to an alternate server only when failover is caused by an unsuccessful connection attempt or a lost connection). |
|
InformixServer |
Name of the Informix database server to which you want to connect. |
|
LoadBalancing |
Sets whether the driver will use client load balancing in its attempts to connect to database servers (primary and alternate). If client load balancing is enabled, the driver uses a random pattern instead of a sequential pattern in its attempts to connect. The default is false (client load balancing is disabled). |
|
PortNumber |
Port listening for connections on the primary database server. This property is supported only for data source connections. |
|
ServerName |
IP address or server name of the primary database server. This property is supported only for data source connections. |