Setting connection properties

Table 2-2 lists the connection properties for jConnect and indicates their default values. You must set the connection properties before you make a connection.

There are two ways to set the driver connection properties:

Use the DriverManager.getConnection( ) method in your application.

When you define the URL.

Driver connection properties set in the URL do not override any corresponding connection properties set in the application using the DriverManager.getConnection( ) method.

To obtain a current list of properties for any driver, use the Driver.getDriverPropertyInfo(String url, Properties props), which returns an array of DriverPropertyInfo objects. The array lists:

Driver properties

Current settings on which the driver properties are based

The URL and props passed in

Driver connection property names are not case-sensitive (jConnect uses the String.equalsIgnoreCase(String) method to compare property names).

**Table 2-2: Connection properties**
Property	Description	Default value
APPLICATIONNAME	A user-defined property. The server side can be programmed to interpret the value given to this property.	Null
BE_AS_JDBC_COMPLIANT_ AS_POSSIBLE (only for jConnect version 5.5 or later)	Adjusts other properties to ensure that jConnect methods respond in a way that is as compliant as possible with the JDBC 2.1 standard. These properties are affected (and overridden) when this property is set to true: CANCEL_ALL (set to false) LANGUAGE CURSOR (set to true for jConnect 4.x, set to false for jConnect 5.x) SELECT_OPENS_CURSOR (set to true) FAKE_METADATA (set to true) GET_BY_NAME_USES_COLUMN_LABEL (set to false)	False
CANCEL_ALL	Determines the behavior of the Statement.cancel( ) method. See “CANCEL_ALL connection property”.	Depends on version setting (see “Setting the jConnect version”.
CHARSET	Specifies the character set for strings passed to the database. If the CHARSET value is null, jConnect will use the server’s default character set to send string data to the server. If you specify a CHARSET, the database must be able to handle characters in that format. If the database cannot do so, a message will be generated indicating that character conversion cannot be properly completed. Note that when using jConnect 5.5 with unichar enabled, jConnect will detect when a client is trying to send characters to the server that cannot be represented in the character set that is being used for the Connection. When that occurs, jConnect will send the character data to the server as unichar data; this allows clients to insert unicode data into unichar/univarchar columns and parameters.	Null
CHARSET_CONVERTER_CLASS	Use this property to specify the character-set converter class you want jConnect to use. jConnect uses the version setting from SybDriver.setVersion(), or the version passed in with the JCONNECT_VERSION property, to determine the default character-set converter class to use. See “Selecting a character-set converter” for details.	Version dependent
CLASS_LOADER	Set this property to a DynamicClassLoader object that you create. The DynamicClassLoader is used to load Java classes that are stored in the database, but which are not in the CLASSPATH at application start-up time. See“Dynamic class loading” for more information.	Null
CONNECTION_FAILOVER	For use with the Java Naming and Directory Interface (JNDI). See “CONNECTION_FAILOVER connection property”.	True
DISABLE_UNICHAR_SENDING (Only for jConnect version 5.5 or later)	When a client application sends unichar characters to the server (along with non-unichar characters), there is a slight performance hit for any character data sent to the database. Because this property defaults to true, clients who wish to send unichar data to the database must set this property value to false. See “Using jConnect to pass Unicode data”.	True
DISABLE_UNPROCESSED_ PARAM_WARNINGS	During results processing for a stored procedure, jConnect often reads return values other than row data. If you do not process the return value, jConnect raises a warning. To disable these warnings (which can help performance), set this property to true.	False
DYNAMIC_PREPARE	Determines whether dynamic SQL prepared statements are precompiled in the database. See “DYNAMIC_PREPARE connection property”.	False
ESCAPE_PROCESSING_DEFAULT	By default, jConnect parses all SQL statements submitted to the database for valid JDBC function escapes. If your application is not going to use JDBC function escapes in its SQL calls, you can set this connection property to false to circumvent this processing. This can provide a slight performance benefit.	True
EXPIRESTRING	A read-only property that contains the license expiration date. Expiration is never except for evaluation copies of jConnect.	Never
FAKE_METADATA (Only for jConnect version 5.5 or later)	When you call the ResultSetMetaData methods getCatalogName, getSchemaName, and getTableName and this property is set to true, the call will return empty strings ("") because the server does not supply useful metadata. When this property is set to false, calling these methods throws a “Not Implemented” SQLException. If you have enabled wide tables and are using an Adaptive Server 12.5 or later, this property setting is ignored, because the server does supply useful metadata.	False
GET_BY_NAME_USES_ COLUMN_LABEL (Only for jConnect version 5.5 or later)	Provides backward compatibility with versions of jConnect earlier than 5.5. With Adaptive Server version 12.5, jConnect has access to more metadata than was previously available. Previous to version 12.5, column name and column alias meant the same thing. jConnect can now differentiate between the two when used with a 12.5 or later Adaptive Server with wide tables enabled. To preserve backward compatibility, set this property to true.If you want calls to getByte, getInt, get* (String columnName) to look at the actual name for the column (called for in the JDBC 2.0 specification), set this property to false.	True
HOSTNAME	The name of the current host.	None The max length is 30 characters and if exceeded, it will be truncated to 30
HOSTPROC	Identifies the application’s process on the host machine.	None
IGNORE_DONE_IN_PROC	When set to true, intermediate update results (as in stored procedures) are not returned, only the final result set.	False
IS_CLOSED_TEST	Allows you to specify what query, if any, is sent to the database when Connection.isClosed() is called. For additional information , see the “Connection.isClosed() and the IS_CLOSED_TEST connection property”.	Null
JCONNECT_VERSION	Use this property to set version-specific characteristics. See “JCONNECT_VERSION connection property”.	5
LANGUAGE	Set this property for error messages returned from the server and for jConnect messages. It must match a language in syslanguages.	Version dependent (see “Setting the jConnect version”).
LANGUAGE_CURSOR	Set this property to true if you want jConnect to use “language cursors” instead of “protocol cursors.” See “Cursor performance”.	False
LITERAL_PARAMS	Use this property primarily when using jConnect with Adaptive Server Anywhere version 5.5. ASA 5.5 requires you to send prepared statement parameters as literals. For all other Sybase databases (including ASA 6 and later), this property can be set to false. When set to true, any parameters set by the setXXX methods in the PreparedStatement interface are inserted literally into the SQL statement when it is executed. If set to false, parameter markers are left in the SQL statement and the parameter values are sent to the server separately.	False
USE_METADATA	When set to true, a DatabaseMetaData object will be created and initialized when you establish a connection. The DatabaseMetaData object is necessary to connect to a specified database. jConnect uses DatabaseMetaData for some features, including Distributed Transaction Management support (JTA/JTS) and dynamic class loading (DCL). If you receive error 010SJ, which indicates that your application requires metadata, install the stored procedures for returning metadata that come with jConnect (see “Installing Stored Procedures” in Chapter 3 of the jConnect for JDBC Installation Guide).	true
PACKETSIZE	Network packet size.	512
PASSWORD	Login password. Set automatically if using the getConnection(String, String, String) method, or explicitly if using getConnection(String, Props).	None
PRELOAD_JARS	A comma-separated list of jar file names that are associated with the CLASS_LOADER that you specify. These jars are loaded at connect time, and are available for use by any other Connection using the same jConnect driver. See “Preloading JARS” for more information.	Null
PROTOCOL_CAPTURE	The PROTOCOL_CAPTURE connection property is used to specify a file for capturing TDS communication between an application and an Adaptive Server.	Null
PROXY	Gateway address. For the HTTP protocol, the URL is http://host:port. To use the HTTPS protocol that supports encryption, the URL is https://host:port/servlet_alias.	None
REMOTEPWD	Remote server passwords for access through server-to-server remote procedure calls. See “Performing server-to-server remote procedure calls”.	None
REPEAT_READ	Determines whether the driver keeps copies of columns and output parameters so that columns can be read out of order or repeatedly. See “REPEAT_READ connection property”.	True
REQUEST_HA_SESSION	This property indicates whether the connecting client wants to begin an HA failover session with a version 12 or later Adaptive Server configured for failover. See “Implementing high availability failover support”. Setting this property to true causes jConnect to attempt a failover login. If you do not set this connection property, a failover session will not start, even if the server is configured for failover. You cannot reset the property once a connection has been made.If you want more flexibility for requesting failover sessions, code the client application to set REQUEST_HA_SESSION at runtime.	False
RMNAME	This property is used to set the Resource Manager name when using distributed transactions (XA). This property will override a Resource Manager name that may be set in an LDAP server entry. See “Distributed transaction management support” for more information.	Null
SECONDARY_SERVER_ HOSTPORT	Sets the hostname and port for the secondary server when the client is using an HA failover session. The value for this property should be in the form of hostName:portNumber. This property is ignored unless you have also set REQUEST_HA_SESSION to true. See “Implementing high availability failover support” for more information.	Null
SELECT_OPENS_CURSOR	If set to true, calls to Statement.executeQuery( ) will automatically generate a cursor when the query contains a “FOR UPDATE” clause. If you have previously called Statement.setFetchSize( ) or Statement.setCursorName( ) on the same statement, a setting of true for SELECT_OPENS_CURSOR has no effect. You may experience some performance degradation when SELECT_OPENS_CURSOR is set to true. See “Using cursors with result sets” for more information on using cursors with jConnect.	False
SERIALIZE_REQUESTS	If set to true, jConnect waits for responses from the server before sending additional requests.	False
SERVICENAME	The name of a back-end database server that a DirectConnect gateway serves. Also used to indicate which database should be used upon connecting to Adaptive Server Anywhere.	None
SESSION_ID	When this property is set, jConnect assumes that an application is trying to resume communication on an existing TDS session held open by the TDS-tunnelling gateway. jConnect skips the login negotiations and forwards all requests from the application to the specified session ID.	Null
SESSION_TIMEOUT	Use this property to specify the amount of time (in seconds) that an http-tunnelled session (created using the jConnect TDS-tunnelling servlet) will remain alive while idle. After the specified time, the connection will be automatically closed. For more information about the TDS-tunnelling servlet, see page §.	Null
SQLINITSTRING	Use this property to define a set of commands to be passed to the database server when a Connection is opened. These must be SQL commands that can be executed using the Statement.executeUpdate( ) method.	Null
STREAM_CACHE_SIZE	Maximum size used to cache statement response streams.	Null (unlimited cache size)
SYBSOCKET_FACTORY	Use this property to enable jConnect to use your custom socket implementation. Set SYBSOCKET_FACTORY either to: The name of a class that implements com.sybase.jdbcx.SybSocketFactory; or “DEFAULT,” which instantiates a new java.net.Socket( ) See “Implementing custom socket plug-ins”.	Null
USER	Login ID. Set automatically if using the getConnection(String, String, String) method, or explicitly if using getConnection(String, Props).	None
VERSIONSTRING	Read-only version information for the JDBC driver.	jConnect driver version

Table 2-2: Connection properties

Property

Description

Default value

APPLICATIONNAME

A user-defined property. The server side can be programmed to interpret the value given to this property.

Null

BE_AS_JDBC_COMPLIANT_ AS_POSSIBLE (only for jConnect version 5.5 or later)

Adjusts other properties to ensure that jConnect methods respond in a way that is as compliant as possible with the JDBC 2.1 standard.

These properties are affected (and overridden) when this property is set to true:

CANCEL_ALL (set to false)
LANGUAGE CURSOR (set to true for jConnect 4.x, set to false for jConnect 5.x)
SELECT_OPENS_CURSOR (set to true)
FAKE_METADATA (set to true)
GET_BY_NAME_USES_COLUMN_LABEL (set to false)

False

CANCEL_ALL

Determines the behavior of the Statement.cancel( ) method. See “CANCEL_ALL connection property”.

Depends on version setting (see “Setting the jConnect version”.

CHARSET

Specifies the character set for strings passed to the database. If the CHARSET value is null, jConnect will use the server’s default character set to send string data to the server. If you specify a CHARSET, the database must be able to handle characters in that format. If the database cannot do so, a message will be generated indicating that character conversion cannot be properly completed. Note that when using jConnect 5.5 with unichar enabled, jConnect will detect when a client is trying to send characters to the server that cannot be represented in the character set that is being used for the Connection. When that occurs, jConnect will send the character data to the server as unichar data; this allows clients to insert unicode data into unichar/univarchar columns and parameters.

Null

CHARSET_CONVERTER_CLASS

Use this property to specify the character-set converter class you want jConnect to use. jConnect uses the version setting from SybDriver.setVersion(), or the version passed in with the JCONNECT_VERSION property, to determine the default character-set converter class to use. See “Selecting a character-set converter” for details.

Version dependent

CLASS_LOADER

Set this property to a DynamicClassLoader object that you create. The DynamicClassLoader is used to load Java classes that are stored in the database, but which are not in the CLASSPATH at application start-up time. See“Dynamic class loading” for more information.

Null

CONNECTION_FAILOVER

For use with the Java Naming and Directory Interface (JNDI). See “CONNECTION_FAILOVER connection property”.

True

DISABLE_UNICHAR_SENDING (Only for jConnect version 5.5 or later)

When a client application sends unichar characters to the server (along with non-unichar characters), there is a slight performance hit for any character data sent to the database. Because this property defaults to true, clients who wish to send unichar data to the database must set this property value to false. See “Using jConnect to pass Unicode data”.

True

DISABLE_UNPROCESSED_ PARAM_WARNINGS

During results processing for a stored procedure, jConnect often reads return values other than row data. If you do not process the return value, jConnect raises a warning. To disable these warnings (which can help performance), set this property to true.

False

DYNAMIC_PREPARE

Determines whether dynamic SQL prepared statements are precompiled in the database. See “DYNAMIC_PREPARE connection property”.

False

ESCAPE_PROCESSING_DEFAULT

By default, jConnect parses all SQL statements submitted to the database for valid JDBC function escapes. If your application is not going to use JDBC function escapes in its SQL calls, you can set this connection property to false to circumvent this processing. This can provide a slight performance benefit.

True

EXPIRESTRING

A read-only property that contains the license expiration date. Expiration is never except for evaluation copies of jConnect.

Never

FAKE_METADATA (Only for jConnect version 5.5 or later)

When you call the ResultSetMetaData methods getCatalogName, getSchemaName, and getTableName and this property is set to true, the call will return empty strings ("") because the server does not supply useful metadata.

When this property is set to false, calling these methods throws a “Not Implemented” SQLException.

If you have enabled wide tables and are using an Adaptive Server 12.5 or later, this property setting is ignored, because the server does supply useful metadata.

False

GET_BY_NAME_USES_ COLUMN_LABEL (Only for jConnect version 5.5 or later)

Provides backward compatibility with versions of jConnect earlier than 5.5.

With Adaptive Server version 12.5, jConnect has access to more metadata than was previously available. Previous to version 12.5, column name and column alias meant the same thing. jConnect can now differentiate between the two when used with a 12.5 or later Adaptive Server with wide tables enabled.

To preserve backward compatibility, set this property to true.If you want calls to getByte, getInt, get* (String columnName) to look at the actual name for the column (called for in the JDBC 2.0 specification), set this property to false.

True

HOSTNAME

The name of the current host.

None The max length is 30 characters and if exceeded, it will be truncated to 30

HOSTPROC

Identifies the application’s process on the host machine.

None

IGNORE_DONE_IN_PROC

When set to true, intermediate update results (as in stored procedures) are not returned, only the final result set.

False

IS_CLOSED_TEST

Allows you to specify what query, if any, is sent to the database when Connection.isClosed() is called. For additional information , see the “Connection.isClosed() and the IS_CLOSED_TEST connection property”.

Null

JCONNECT_VERSION

Use this property to set version-specific characteristics. See “JCONNECT_VERSION connection property”.

LANGUAGE

Set this property for error messages returned from the server and for jConnect messages. It must match a language in syslanguages.

Version dependent (see “Setting the jConnect version”).

LANGUAGE_CURSOR

Set this property to true if you want jConnect to use “language cursors” instead of “protocol cursors.” See “Cursor performance”.

False

LITERAL_PARAMS

Use this property primarily when using jConnect with Adaptive Server Anywhere version 5.5. ASA 5.5 requires you to send prepared statement parameters as literals. For all other Sybase databases (including ASA 6 and later), this property can be set to false.

When set to true, any parameters set by the setXXX methods in the PreparedStatement interface are inserted literally into the SQL statement when it is executed.

If set to false, parameter markers are left in the SQL statement and the parameter values are sent to the server separately.

False

USE_METADATA

When set to true, a DatabaseMetaData object will be created and initialized when you establish a connection. The DatabaseMetaData object is necessary to connect to a specified database.

jConnect uses DatabaseMetaData for some features, including Distributed Transaction Management support (JTA/JTS) and dynamic class loading (DCL).

If you receive error 010SJ, which indicates that your application requires metadata, install the stored procedures for returning metadata that come with jConnect (see “Installing Stored Procedures” in Chapter 3 of the jConnect for JDBC Installation Guide).

true

PACKETSIZE

Network packet size.

512

PASSWORD

Set automatically if using the getConnection(String, String, String) method, or explicitly if using getConnection(String, Props).

None

PRELOAD_JARS

A comma-separated list of jar file names that are associated with the CLASS_LOADER that you specify. These jars are loaded at connect time, and are available for use by any other Connection using the same jConnect driver. See “Preloading JARS” for more information.

Null

PROTOCOL_CAPTURE

The PROTOCOL_CAPTURE connection property is used to specify a file for capturing TDS communication between an application and an Adaptive Server.

Null

PROXY

Gateway address. For the HTTP protocol, the URL is http://host:port.

To use the HTTPS protocol that supports encryption, the URL is https://host:port/servlet_alias.

None

REMOTEPWD

Remote server passwords for access through server-to-server remote procedure calls. See “Performing server-to-server remote procedure calls”.

None

REPEAT_READ

Determines whether the driver keeps copies of columns and output parameters so that columns can be read out of order or repeatedly. See “REPEAT_READ connection property”.

True

REQUEST_HA_SESSION

This property indicates whether the connecting client wants to begin an HA failover session with a version 12 or later Adaptive Server configured for failover. See “Implementing high availability failover support”.

Setting this property to true causes jConnect to attempt a failover login. If you do not set this connection property, a failover session will not start, even if the server is configured for failover.

You cannot reset the property once a connection has been made.If you want more flexibility for requesting failover sessions, code the client application to set REQUEST_HA_SESSION at runtime.

False

RMNAME

This property is used to set the Resource Manager name when using distributed transactions (XA). This property will override a Resource Manager name that may be set in an LDAP server entry. See “Distributed transaction management support” for more information.

Null

SECONDARY_SERVER_ HOSTPORT

Sets the hostname and port for the secondary server when the client is using an HA failover session. The value for this property should be in the form of hostName:portNumber. This property is ignored unless you have also set REQUEST_HA_SESSION to true. See “Implementing high availability failover support” for more information.

Null

SELECT_OPENS_CURSOR

If set to true, calls to Statement.executeQuery( ) will automatically generate a cursor when the query contains a “FOR UPDATE” clause.

If you have previously called Statement.setFetchSize( ) or Statement.setCursorName( ) on the same statement, a setting of true for SELECT_OPENS_CURSOR has no effect.

You may experience some performance degradation when SELECT_OPENS_CURSOR is set to true.

See “Using cursors with result sets” for more information on using cursors with jConnect.

False

SERIALIZE_REQUESTS

If set to true, jConnect waits for responses from the server before sending additional requests.

False

SERVICENAME

The name of a back-end database server that a DirectConnect gateway serves. Also used to indicate which database should be used upon connecting to Adaptive Server Anywhere.

None

SESSION_ID

When this property is set, jConnect assumes that an application is trying to resume communication on an existing TDS session held open by the TDS-tunnelling gateway. jConnect skips the login negotiations and forwards all requests from the application to the specified session ID.

Null

SESSION_TIMEOUT

Use this property to specify the amount of time (in seconds) that an http-tunnelled session (created using the jConnect TDS-tunnelling servlet) will remain alive while idle. After the specified time, the connection will be automatically closed. For more information about the TDS-tunnelling servlet, see page §.

Null

SQLINITSTRING

Use this property to define a set of commands to be passed to the database server when a Connection is opened. These must be SQL commands that can be executed using the Statement.executeUpdate( ) method.

Null

STREAM_CACHE_SIZE

Maximum size used to cache statement response streams.

Null (unlimited cache size)

SYBSOCKET_FACTORY

Use this property to enable jConnect to use your custom socket implementation.

Set SYBSOCKET_FACTORY either to:

The name of a class that implements com.sybase.jdbcx.SybSocketFactory; or
“DEFAULT,” which instantiates a new java.net.Socket( )

See “Implementing custom socket plug-ins”.

Null

USER

Set automatically if using the getConnection(String, String, String) method, or explicitly if using getConnection(String, Props).

None

VERSIONSTRING

Read-only version information for the JDBC driver.

jConnect driver version

The following code is an example of setting connection properties. The sample programs provided with jConnect also contain examples of setting these properties.

Properties props = new Properties(); props.put("user", "userid"); props.put("password", "user_password"); /* * If the program is an applet that wants to access * a server that is not on the same host as the * web server, then it uses a proxy gateway. */ props.put("proxy", "localhost:port"); /* * Make sure you set connection properties before * attempting to make a connection. You can also * set the properties in the URL. */ Connection con = DriverManager.getConnection ("jdbc:sybase:Tds:host:port", props);