11. Understanding JDBC Connectivity : JDBC Driver Interface : JDBC Driver and Data Source Classes : JDBC Driver Properties
 
Share this page                  
JDBC Driver Properties
Driver properties allow applications to establish connection parameters that are driver-dependent. JDBC Driver properties can be specified as follows:
• As connection URL attributes as a Java Properties parameter to a DriverManager.getConnection() method
• As Java system properties
• 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
During Ingres installation, the JDBC Driver Properties Generator (iijdbcprop) reads the Ingres configuration and generates the corresponding JDBC driver properties file, named iijdbc.properties.
A default properties file (typically iijdbc.properties) is loaded automatically by the JDBC Driver when the driver class is loaded. The file must reside in a location accessible by the class loader used to load the driver. In general, this requires that the properties file directory 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 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.
This property can be used if the user has no DBMS user ID and password assigned (see dbms_user and dbms_password 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 associated with the DBMS session (Ingres -u flag, can require admin privileges).
dbms_password
DBPWD
The user's DBMS password (Ingres -P flag).
compression
COMPRESS
Whether data is compressed over the network. Valid values are:
off–(Default) Compression off
on–Compression on
connect_pool
POOL
Server connection pool control. Valid values 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. Valid values are:
on–Uses select loops to retrieve query results
off–(Default) Uses cursors
For further details, see Cursors and Select Loops.
autocommit_mode
AUTO
Autocommit cursor handling mode. Valid values are:
dbms–(Default) autocommit processing is done by the DBMS Server
single–DAS enforces single cursor operation during autocommit
multi–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. Valid values are:
dbms–Concurrency is determined by the DBMS Server
update–Provides updateable cursors
readonly–(Default) Provides non-updateable cursors
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. Valid values are:
connect–(Default) Only the vnode connection information is used to establish the connection.
login–Both the vnode connection and login information are used to establish the connection.
For further details, see JDBC User Authentication.
encryption
ENCRYPT
Defines the default encryption mode used by client connections. Valid values are:
on–Encryption is required and occurs unless no compatible encryption mechanism is available. Connection fails if encryption is not possible.
off–(Default) Encryption is disabled.
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 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 time zone 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_alias
DATE
Specifies the data type of columns created using the alias keyword "date". Valid values are: "ansidate" or "ingresdate". Default value is "ansidate" if the property send_ingres_dates is set to false, otherwise it is "ingresdate". 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.
send_ingres_dates
SEND_INGDATE
Specifies whether date/time/timestamp values should be sent as INGRESDATE data type. Valid values are:
false–Values sent as ANSI TIMESTAMP WITH TIMEZONE type
true–Values sent as INGRESDATE type
Default value is false if date_alias property is set to "ansidate"; otherwise it is true. Unlike date_format and date_alias, this property is internal to the driver, not sent to the DBMS, and affects the processing of query text.
send_integer_booleans
SEND_INTBOOL
Specifies if Boolean parameters are converted to tinyint values when sent to the DBMS. Valid values are:
true–Boolean parameters are converted to tinyint values
false–(Default) Boolean parameters are sent as Boolean values
identity_query
IDENTITY
Enables or disables the identity query. Valid values are:
on–(Default) Identity query is issued if no table key or object key is received and other conditions permit. This setting provides the best behavior for applications that use only table or object keys or only identity columns. 
off–Identity query is not issued and identity values are not returned. This setting is appropriate if only table or object keys are used.
metadata_underscore
META_UNDER
Enables or disables the underscore character, ‘_’, as a pattern wildcard in DatabaseMetaData methods whose parameters are defined as patterns. Valid values are:
true–(Default) Underscore character is treated as a wildcard in metadata patterns.
false–Underscore is treated as a literal character in metadata patterns.
Attributes can also be specified using the property name as the attribute name. Thus "UID=user1" and "user=user1" are semantically the same.
JDBC Driver Properties Generator (iijdbcprop)
The iijdbcprop utility automatically generates all supported JDBC properties. The utility runs automatically during installation but can be run at any time.
This utility provides the following benefits:
• Automatically generates all JDBC properties that match related Ingres environment variables, such as II_TIMEZONE_NAME, II_DECIMAL, II_DATE_FORMAT, II_MONEY_FORMAT and II_MONEY_PREC. These properties can keep the JDBC Driver behavior synchronized with an Ingres or Vector installation, since the JDBC Driver does not have access to the Ingres or Vector environment variables and is often deployed on a machine separate from Ingres or Vector.
• Reduces typing errors when entering JDBC properties by hand. All available JDBC properties are generated, but properties not in the Ingres/Vector configuration files are commented out.
The iijdbcprop command writes the iijdbc.properties file into the directory:
UNIX: $II_SYSTEM/ingres/files
Windows: %II_SYSTEM%\ingres\files
VMS: II_SYSTEM:[INGRES.FILES]
During loading of the JDBC Driver by the class loader, the directory containing the iijdbc.properties file must be specified in the Java environment variable CLASSPATH.
If an Ingres JDBC application is connecting to a remote Data Access Server (that is, Ingres is not installed on the machine running iijdbc.jar), the iijdbc.properties file from the remote Ingres installation can be copied to the machine running iijdbc.jar. The directory of the iijdbc.properties file must be included in the CLASSPATH (see Set CLASSPATH Environment).
Example Entries--For example, to turn on tracing in the driver, uncomment the desired trace entries in the iijdbc.properties file by removing the leading # sign, and then provide appropriate values for them as shown here.
On UNIX, the following entries in iijdbc.properties file will produce a JDBC Driver trace file under the /tmp directory called jdbc_driver.log, provided the $II_SYSTEM/ingres/files directory is in the CLASSPATH.
ingres.jdbc.trace.log=/tmp/jdbc_driver.log
ingres.jdbc.trace.drv=5
ingres.jdbc.trace.msg=3
For details on the iijdbcprop command, see the Command Reference Guide.