JDBC Driver Interface

This section details the Ingres JDBC Driver interface class files and their associated properties. It also includes instructions for loading and accessing the driver.

JDBC Driver and Data Source Classes

The Ingres JDBC driver and data source classes are located in the Java package, com.ingres.jdbc.

These packages are contained in the Java archive iijdbc.jar, which includes the following class files:

Class	Implemented JDBC Interface
com.ingres.jdbc.IngresDriver	The Ingres implementation of the JDBC Driver interface (java.sql.Driver).
com.ingres.jdbc.IngresDataSource	The Ingres implementation of the JDBC DataSource interface (javax.sql.DataSource).
com.ingres.jdbc.IngresCPDataSource	The Ingres implementation of the JDBC ConnectionPoolDataSource interface (javax.sql.ConnectionPoolDataSource).
com.ingres.jdbc.IngresXADataSource	The Ingres implementation of the JDBC XADataSource interface (javax.sql.XADataSource).

Note: The original Ingres JDBC Driver and DataSources classes contained in the Java archive iijdbc.jar under the Java package path of "ca.ingres.jdbc" are moved to the package path of "com.ingres.jdbc". The iijdbc.jar archive included with Ingres 2006 also contains the original classes for backward compatibility. The original "ca.ingres.jdbc" package path and classes will be removed from iijdbc.jar in the next major release. Existing references to "ca.ingres.jdbc" classes will continue to work, but should be changed when convenient. New references should use the package path of "com.ingres.jdbc".

JDBC Driver Properties

Driver properties allow applications to establish connection parameters that are driver-dependent. Ingres JDBC Driver properties can be specified as connection URL attributes as a Java Properties parameter to a DriverManager.getConnection() method, as Java system properties, or in a properties file. Attribute and property names are given below.

When specified as system properties or in a property file, the property key must be of the form ingres.jdbc.property.<property name>. A default properties file is loaded automatically by the Ingres JDBC Driver when the driver class is loaded. The default properties file is named iijdbc.properties and must reside in a location accessible by the class loader used to load the driver. In general, this requires the properties file directory to be included in the Java environment variable CLASSPATH.

An alternate properties file can also be specified using the system property ingres.jdbc.property_file. The directory path of the property file can be specified or the property file can be placed in a directory accessible as described above for the default properties file. Properties are searched in the following order: URL attributes, getConnection() property set, system properties, alternate properties file, and default properties file.

The Ingres JDBC Driver supports the following properties:

Property	Attribute	Description
user	UID	The user ID on the target DBMS Server machine. See the description of the vnode_usage property in this table.
password	PWD	The user's operating system password.
role	ROLE	The desired role identifier. If a role password is required, include it with the role name as follows: name/password.
group	GRP	The user's group identifier.
dbms_user	DBUSR	The user name to be associated with the DBMS session (Ingres -u flag, can require admin privileges).
dbms_password	DBPWD	The user's DBMS password (Ingres -P flag).
connect_pool	POOL	Server connection pool control. Available options are: off–requests a non-pooled connection when server pooling is enabled on–-requests a pooled connection when server pooling is optional. The default is to allow the DAS configuration to determine pooling.
select_loop	LOOP	Select loop vs. cursor queries. Available options are: on–uses select loops to retrieve query results off–uses cursors (default). For further details, see Cursors and Select Loops.
autocommit_mode	AUTO	Autocommit cursor handling mode. Available options are: dbms–autocommit processing is done by the DBMS Server (default) single–DAS DAS enforces single cursor operation during autocommit multi–DAS DAS simulates autocommit operations when more than one cursor is open. For further details, see How Transactions Are Autocommitted.
cursor_mode	CURSOR	Default cursor concurrency mode, which determines the concurrency of cursors that have no concurrency explicitly assigned. Available options are: dbms–-concurrency is determined by the DBMS Server update–provides updateable cursors readonly–provides non-updateable cursors (default) Further details are provided in Cursors and Result Set Characteristics.
vnode_usage	VNODE	Allows the JDBC application to control the portions of the vnode information that are used to establish the connection to the remote DBMS server. Available options are: connect–Only the vnode connection information is used to establish the connection. (default) login–Both the vnode connection and login information are used to establish the connection. For further details, see JDBC User ID Options.
char_encode	ENCODE	Specifies the Java character encoding used for conversions between Unicode and character data types. Generally, the character encoding is determined automatically by the driver from the DAS DAS installation character set. This property allows an alternate character encoding to be specified (if desired) or a valid character encoding to be used when the driver is unable to map the server's character set.
timezone	TZ	Specifies the Ingres timezone associated with the client's location. Corresponds to the Ingres environment variable II_TIMEZONE_NAME and is assigned the same values. This property is not used directly by the driver but is sent to the DBMS and affects the processing of dates.
decimal_char	DECIMAL	Specifies the character to be used as the decimal point in numeric literals. Corresponds to the Ingres environment variable II_DECIMAL and is assigned the same values. This property is not used directly by the driver but is sent to the DBMS and affects the processing of query text.
date_format	DATE_FMT	Specifies the Ingres format for date literals. Corresponds to the Ingres environment variable II_DATE_FORMAT and is assigned the same values. This property is not used directly by the driver, but is sent to the DBMS and affects the processing of query text.
money_format	MNY_FMT	Specifies the Ingres format for money literals. Corresponds to the Ingres environment variable II_MONEY_FORMAT and is assigned the same values. This property is not used directly by the driver but is sent to the DBMS and affects the processing of query text.
money_precision	MNY_PREC	Specifies the precision of money data values. Corresponds to the Ingres environment variable II_MONEY_PREC and is assigned the same values. This property is not used directly by the driver but is sent to the DBMS and affects the processing of money values.

Attributes can also be specified using the property name as the attribute name. Thus "UID=user1" and "user=user1" are semantically the same.

Data Source Properties

A data source configuration is a collection of information that identifies the target database to which the driver connects. The Data Source classes support the following data source properties and associated getter/setter methods.

DS Property	Description
description	Description of the data source.
serverName	Server host name or network address (required).
portName	Symbolic port ID (required). A port ID must be provided either numerically or symbolically.
portNumber	Numeric port ID (required). A port ID must be provided either numerically or symbolically.
databaseName	Database name (required).
user	User's ID. (A user ID is required when the DAS is not on the same machine as the JDBC client; otherwise this property is optional.)
password	User's password. (A password is required when the DAS is not on the same machine as the JDBC client; otherwise this property is optional.)
roleName	DBMS role identifier.
groupName	DBMS group identifier.
dbmsUser	User ID for the DBMS session (-u flag).
dbmsPassword	User's DBMS password.
connectionPool	Use pooled connection: 'off' or 'on'.
autocommitMode	Autocommit cursor handling: 'dbms', 'single', 'multi'.
selectLoop	Select loop processing: 'off', or 'on'.
cursorMode	Default cursor concurrency: 'dbms', 'update', 'readonly'.
vnodeUsage	Vnode usage for DBMS Server access: 'login', 'connect'.
charEncode	Java character encoding.
timeZone	Ingres timezone
decimalChar	Ingres decimal character
dateFormat	Ingres date format
moneyFormat	Ingres money format
moneyPrecision	Ingres money precision

Note that the data source properties marked as "required" correspond to parameters contained in a connection URL. For a description of these parameters, see Establish JDBC Driver Connection. The remaining Data Source properties correspond to the driver properties defined in JDBC Driver Properties.

Additional Data Source Properties

In addition to the DataSource class properties, the ConnectionPoolDataSource and XADataSource classes support the following properties and associated getter/setter methods:

DS Property	Description
initialPoolSize	Initial connection pool size
minPoolSize	Minimum connection pool size
maxPoolSize	Maximum connection pool size
maxIdleTime	Maximum time in connection pool
propertyCycle	Wait time for checking the connection pool

How the Driver Is Loaded

The Ingres JDBC Driver can be loaded by an application or applet by using one of these methods:

Adding the driver class, com.ingres.jdbc.IngresDriver, to the JDBC DriverManager system property "jdbc.drivers"
Adding the following Java statement to the application/applet prior to attempting to establish a connection using the Ingres JDBC Driver:
Class.forName( "com.ingres.jdbc.IngresDriver" ).newInstance();

Depending on the Java environment, calling the forName() method can be sufficient to load and initialize the Ingres JDBC Driver classes. Some environments, most notably older releases of Microsoft Internet Explorer, require the instantiation of an Ingres JDBC Driver object to fully initialize the driver.

DriverManager.getConnection() Method—Establish JDBC Driver Connection

An Ingres JDBC Driver connection can be established using a DriverManager.getConnection() method with a URL in the following format:

jdbc:ingres://host:port/db;attr=value

where:

host
Is the network name or address of the host on which the target DAS is running. TCP/IPv6 addresses (colon-hexadecimal format) must be enclosed in square brackets, for example: [::1].
port
Is the network port used by the DAS. This can be a numeric port number or an Ingres symbolic port address such as II7.
db
Is the target database specification. Any valid Ingres database designation can be used including vnode and server class (that is, vnode::dbname/server_class).
attr=value
(Optional) Is the attribute name and value pair. Multiple attribute pairs are separated by a semi-colon.

Attributes represent driver properties that are implementation-specific and can be used to configure the new connection. For details, see JDBC Driver Properties.

Note: A user ID and password are required when making remote connections and can be included as parameters to the getConnection() method as driver properties or as URL attributes.