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.

Set the connection properties 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	Specifies an application name. This is 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	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 "false" for jConnect 6.0, set to "false" for jConnect 6.0) 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 uses the default character set of the server 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 is generated indicating that character conversion cannot be properly completed. When using jConnect 6.0 with unichar enabled, jConnect detects 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 sends the character data to the server as unichar data, which allows clients to insert Unicode data into unichar/univarchar columns and parameters.	Null
CHARSET_CONVERTER_CLASS	Specifies 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	A property you set 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“Using dynamic class loading” for more information.	Null
CONNECTION_FAILOVER	Used with the Java Naming and Directory Interface (JNDI). See “CONNECTION_FAILOVER connection property”.	True
DISABLE_UNICHAR_SENDING	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	Disables 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	Circumvents processing of JDBC function escapes in SQL statements. 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 avoid this processing. This can provide a slight performance benefit.	True
EXPIRESTRING	Contains the license expiration date. Expiration is never except for evaluation copies of jConnect. This is a read-only property.	Never
FAKE_METADATA	Returns phony metadata. When you call the ResultSetMetaData methods getCatalogName, getSchemaName, and getTableName and this property is set to "true," the call returns 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	Provides backward compatibility with versions of jConnect earlier than 6.0. 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
GSSMANAGER_CLASS	Specifies a third-party implementation of the org.ietf.jgss.GSSManager class. This property can be set to a string or a GSSManager object. If the property is set to a string, the value should be the fully qualified class name of the third-party GSSManager implementation. If the property is set to an object, the object must extend the org.ietf.jgss.GSSManager class. See Chapter 3, “Security” for more information.	Null
HOSTNAME	Identifies the name of the current host.	None. The max length is 30 characters and, if exceeded, it is truncated to 30.
HOSTPROC	Identifies the application process on the host machine.	None
IGNORE_DONE_IN_PROC	Determines that 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 “Using Connection.isClosed and IS_CLOSED_TEST”.	Null
JCONNECT_VERSION	Sets version-specific characteristics. See “JCONNECT_VERSION connection property”.	6
LANGUAGE	Sets the language for error messages returned from the server and for jConnect messages. The setting must match a language in syslanguages.	Version dependent. See “Setting the jConnect version”.
LANGUAGE_CURSOR	Determines that jConnect uses “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	Creates and initializes a DatabaseMetaData object 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	Identifies the network packet size.	512
PASSWORD	Identifies the login password. Set automatically if using the getConnection(String, String, String) method, or explicitly if using getConnection(String, Props).	None
PRELOAD_JARS	Contains a comma-separated list of .jar file names that are associated with the CLASS_LOADER that you specify. These .jar files are loaded at connect time, and are available for use by any other connection using the same jConnect driver. See “Preloading .jar files” for more information.	Null
PROTOCOL_CAPTURE	Specifies a file for capturing TDS communication between an application and an Adaptive Server.	Null
PROXY	Specifies a 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
QUERY_TIMEOUT_CANCELS_ALL	Forces jConnect to cancel all statements on a connection when a read timeout occurs. This can be useful when a client has called Statement.execute, and a deadlock occurs, for example, when trying to read from a table that is being updated in another transaction.	False
REMOTEPWD	Contains 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	Indicates whether the connecting client wants to begin an high availability (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 does 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
REQUEST_KERBEROS_SESSION	Determines whether jConnect uses Kerberos for authentication. If this property is set to "true," a value for the SERVICE_PRINCIPAL_NAME property must also be specified. You may also wish to provide a value for the GSSMANAGER_CLASS property. See Chapter 3, “Security” for more information.	False
RMNAME	Sets the Resource Manager name when using distributed transactions (XA). This property overrides 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	Determines whether calls to Statement.executeQuery 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	Determines whether jConnect waits for responses from the server before sending additional requests.	False
SERVICENAME	Indicates 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
SERVICE_PRINCIPAL_NAME	Used when establishing a Kerberos connection to Adaptive Server Enterprise. The value of this property should correspond both to the server entry in your Key Distribution Center (KDC) and to the server name under which your database is running. The value of the SERVICE_PRINCIPAL_NAME property is ignored if the REQUEST_KERBEROS_SESSION property is set to "false." See Chapter 3, “Security” for more information.	Null
SESSION_ID	A TDS 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	Specifies the amount of time (in seconds) that an HTTP-tunnelled session (created using the jConnect TDS-tunnelling servlet) remains alive while idle. After the specified time, the connection is automatically closed. For more information about the TDS-tunnelling servlet, see page §.	Null
SQLINITSTRING	Defines 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	Specifies the maximum size used to cache statement response streams.	Null (unlimited cache size)
SYBSOCKET_FACTORY	Enables 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( ) Use this property to make an SSL connection to your database. See “Implementing custom socket plug-ins”.	Null
USER	Specifies the login ID. Set automatically if using the getConnection(String, String, String) method, or explicitly if using getConnection(String, Props).	None
VERSIONSTRING	Provides read-only version information for the JDBC driver.	jConnect driver version

Table 2-2: Connection properties

Property

Description

Default value

APPLICATIONNAME

Specifies an application name. This is 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

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 "false" for jConnect 6.0, set to "false" for jConnect 6.0)
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 uses the default character set of the server 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 is generated indicating that character conversion cannot be properly completed.

When using jConnect 6.0 with unichar enabled, jConnect detects 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 sends the character data to the server as unichar data, which allows clients to insert Unicode data into unichar/univarchar columns and parameters.

Null

CHARSET_CONVERTER_CLASS

Specifies 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

A property you set 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“Using dynamic class loading” for more information.

Null

CONNECTION_FAILOVER

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

True

DISABLE_UNICHAR_SENDING

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

Disables 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

Circumvents processing of JDBC function escapes in SQL statements. 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 avoid this processing. This can provide a slight performance benefit.

True

EXPIRESTRING

Contains the license expiration date. Expiration is never except for evaluation copies of jConnect. This is a read-only property.

Never

FAKE_METADATA

Returns phony metadata. When you call the ResultSetMetaData methods getCatalogName, getSchemaName, and getTableName and this property is set to "true," the call returns 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

Provides backward compatibility with versions of jConnect earlier than 6.0.

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

GSSMANAGER_CLASS

Specifies a third-party implementation of the org.ietf.jgss.GSSManager class.

This property can be set to a string or a GSSManager object.

If the property is set to a string, the value should be the fully qualified class name of the third-party GSSManager implementation. If the property is set to an object, the object must extend the org.ietf.jgss.GSSManager class. See Chapter 3, “Security” for more information.

Null

HOSTNAME

Identifies the name of the current host.

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

HOSTPROC

Identifies the application process on the host machine.

None

IGNORE_DONE_IN_PROC

Determines that 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 “Using Connection.isClosed and IS_CLOSED_TEST”.

Null

JCONNECT_VERSION

Sets version-specific characteristics. See “JCONNECT_VERSION connection property”.

LANGUAGE

Sets the language for error messages returned from the server and for jConnect messages. The setting must match a language in syslanguages.

Version dependent. See “Setting the jConnect version”.

LANGUAGE_CURSOR

Determines that jConnect uses “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

Creates and initializes a DatabaseMetaData object 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

Identifies the network packet size.

512

PASSWORD

Identifies the login password.

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

None

PRELOAD_JARS

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

Null

PROTOCOL_CAPTURE

Specifies a file for capturing TDS communication between an application and an Adaptive Server.

Null

PROXY

Specifies a 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

QUERY_TIMEOUT_CANCELS_ALL

Forces jConnect to cancel all statements on a connection when a read timeout occurs. This can be useful when a client has called Statement.execute, and a deadlock occurs, for example, when trying to read from a table that is being updated in another transaction.

False

REMOTEPWD

Contains 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

Indicates whether the connecting client wants to begin an high availability (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 does 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

REQUEST_KERBEROS_SESSION

Determines whether jConnect uses Kerberos for authentication. If this property is set to "true," a value for the SERVICE_PRINCIPAL_NAME property must also be specified.

You may also wish to provide a value for the GSSMANAGER_CLASS property. See Chapter 3, “Security” for more information.

False

RMNAME

Sets the Resource Manager name when using distributed transactions (XA). This property overrides 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

Determines whether calls to Statement.executeQuery 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

Determines whether jConnect waits for responses from the server before sending additional requests.

False

SERVICENAME

Indicates 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

SERVICE_PRINCIPAL_NAME

Used when establishing a Kerberos connection to Adaptive Server Enterprise. The value of this property should correspond both to the server entry in your Key Distribution Center (KDC) and to the server name under which your database is running.

The value of the SERVICE_PRINCIPAL_NAME property is ignored if the REQUEST_KERBEROS_SESSION property is set to "false." See Chapter 3, “Security” for more information.

Null

SESSION_ID

A TDS 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

Specifies the amount of time (in seconds) that an HTTP-tunnelled session (created using the jConnect TDS-tunnelling servlet) remains alive while idle. After the specified time, the connection is automatically closed. For more information about the TDS-tunnelling servlet, see page §.

Null

SQLINITSTRING

Defines 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

Specifies the maximum size used to cache statement response streams.

Null (unlimited cache size)

SYBSOCKET_FACTORY

Enables 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( )

Use this property to make an SSL connection to your database.

See “Implementing custom socket plug-ins”.

Null

USER

Specifies the login ID.

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

None

VERSIONSTRING

Provides 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);