List of jConnect connection properties

ALTERNATE_ SERVER_NAME

Specifies the alternate server name used by the primary and secondary database in a mirrored SQL Anywhere environment. The primary and secondary database use the same alternate server name so that client applications can connect to the current primary server without knowing in advance which of the two servers is the primary server.

The JDBC URL syntax is still jdbc:sybase:Tds:<hostname>:<port#>/database?connection_property=value;. However, when ALTERNATE_SERVER_NAME is set, jConnect ignores the values of the hostname and port variables. Instead, jConnect uses the SQL Anywhere UDP discovery protocol to determine the current primary server.

For information about database mirroring, see the SQL Anywhere Server - Database Administration.

Null

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 3.0 standard.

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

• CANCEL_ALL (set to "false")

• LANGUAGE CURSOR (set to “false”)

• SELECT_OPENS_CURSOR (set to "true")

• FAKE_METADATA (set to "true")

• GET_BY_NAME_USES_COLUMN_LABEL (set to "false")

False

CACHE_COLUMN_ METADATA

If you repeatedly use PreparedStatement or CallableStatement objects that perform SELECT queries, setting CACHE_COLUMN_ METADATA to true can improve performance. When set to true, the statement remembers the ResultSet Metadata information associated with the SELECT query results from the first execution of the statement. On subsequent executions, the metadata is re-used without having to be reconstructed. This saves CPU time through the use of additional memory.

False

CANCEL_ALL

Specifies the behavior of the Statement.cancel method:

• If CANCEL_ALL is false, invoking Statement.cancel cancels only the Statement object on which it is invoked. Thus, if stmtA is a Statement object, stmtA.cancel cancels the execution of the SQL statement contained in stmtA in the database, but no other statements are affected. stmtA is canceled whether it is in cache waiting to execute or has started to execute and is waiting for results.

• If CANCEL_ALL is true, invoking Statement.cancel cancels not only the object on which it is invoked, but also any other Statement objects on the same connection that have executed and are waiting for results.

The following example sets CANCEL_ALL to “false.” props is a Properties object for specifying connection properties:

props.put("CANCEL_ALL", "false");

• True – for JCONNECT_VERSION <= “3”

• False – for JCONNECT_VERSION >= “4”

CAPABILITY_TIME

Used only when JCONNECT_VERSION >= 6. When jConnect is connected to a server that supports the TIME datatype, and all parameters of type java.sql.Time or escape literals {t ...} are processed as TIME. Previous versions of jConnect treat such parameters as DATETIME and prepend '1970-01-01' to the java.sql.Time parameter. If the underlying datatype is datetime or smalldatetime the date part also gets stored in the database. In jConnect 6.0 or later, when TIME is processed, the server converts time to the underlying datatype and will prepend its own base year. This can result in incompatibilities between old and new data. If you are using datetime or smalldatetime datatypes for java.sql.Time, then for backward compatibility you should leave CAPABILITY_TIME as false. Leaving this property as false forces jConnect to process java.sql.Time parameters or escape literals {t ...} as DATETIME regardless of the server capability of handling TIME datatype.Setting this property to true will cause jConnect to process java.sql.Time parameters as TIME datatype when connected to Adaptive Server. Sybase recommends you leave this property as false if you are using smalldatetime or datetime columns to store time values.

False

CAPABILITY_ WIDETABLE

If you do not require JDBC ResultSetMetaData like Column name as a performance improvement, you can set this to “false.” The result is that less data is exchanged over the network and increases performance. Unless you are using EAServer, Sybase recommends that you use the default setting. See “Using wide table support for Adaptive Server”.

False

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.

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. See Table 2-1.

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

CRC

When this property is set to true, the update counts that are returned are cumulative counts that include updates directly affected by the statement executed and any triggers invoked as a result of the statement being executed.

false

DATABASE

Use this property to specify the database name for a connection when the connection information is obtained from a Sybase interfaces file. The URL of an interfaces file cannot supply the database name.

null

DEFAULT_QUERY_ TIMEOUT

When this connection property is set, it is used as the default query timeout for any statements created on this connection.

0 (no timeout)

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. This property defaults to false in jConnect 6.05 and later. Clients using older versions of jConnect who wish to send unichar data to the database must set this property to false. See “Using jConnect to pass Unicode data”.

Version-dependent

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

ENABLE_BULK_ LOAD

Specifies whether to use bulk load to insert rows to the database. Values:

• False – disables bulk load.

• True or ARRAYINSERT_WITH_MIXED_STATEMENTS – enables bulk load with row-level logging and allows your application to execute other statements during the bulk load operation.

• ARRAYINSERT – enables bulk load with row-level logging, but your application cannot execute other statements during the bulk load operation.

• BCP – enables bulk load with page-level logging; your application cannot execute other statements during the bulk load operation.

False

ENABLE_SERVER_ PACKETSIZE

Specifies if the connection packet size is set to the value suggested by the server. If set to true, the driver does not use PACKETSIZE connection property and the server is free to use any value between 512 and the maximum packet size. If set to false, the PACKETSIZE connection property is used.

True

ENCRYPT_ PASSWORD

Allows a secure login. When this property is set to true, both login and remote site passwords are encrypted before being sent to the server. Passwords are no longer sent in clear text.

ENCRYPT_PASSWORD has precedence over RETRY_WITH_NO_ENCRYPTION. For more information about password encryption, see “Using password encryption”.

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.

Additionally, ESCAPE_PROCESSING_DEFAULT helps with backend servers such as Sybase IQ that use curly braces as part of the SQL syntax.

True

EXPIRESTRING

Contains the license expiration date. Expiration is set to 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.

False

GET_BY_NAME_ USES_COLUMN_ LABEL

Provides backward compatibility with versions of jConnect earlier than 6.0.

With Adaptive Server version 12.5 and later, jConnect has access to more metadata than was previously available. Prior 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, set this property to “false.”

True

GET_COLUMN_ LABEL_FOR_NAME

Maintains backward compatibility with jConnect 5.5 or earlier, where a call to ResultMetaData.getColumnName returns the column label rather than the column name. Values:

• True – ResultMetaData.getColumnName returns column label

• False – ResultMetaData.getColumnName returns column name

False

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

IMPLICIT_CURSOR_ FETCH_SIZE

Use this property with the SELECT_OPENS_CURSOR property to force jConnect to open a read-only cursor on every select query that is sent to the database. The cursor has a fetch size of the value set in this property, unless overridden by the Statement.setFetchSize method.

0

INTERNAL_QUERY_ TIMEOUT

Use this property to set the query timeout that will be used by statements internally created and executed by jConnect. This may prevent application failures if internal commands do not complete in a reasonable time.

0 (no timeout)

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

J2EE_TCK_ COMPLIANT

When this property is set to true, the jConnect driver enables behavior that is compliant with the J2EE 1.4 technology compatibility kit (TCK) test suite, which causes some loss of performance. Therefore, Sybase recommends using the default value of false.

false

JCE_PROVIDER_ CLASS

Specifies the Java Cryptography Extension (JCE) provider used in RSA encryption algorithms.

The bundled JCE provider.

JCONNECT_VERSION

Sets version-specific characteristics. See “Using JCONNECT_ VERSION”.

7

LANGUAGE

Specifies the language in which messages from jConnect and the server appear. The setting must match a language in syslanguages because server messages are localized according to the language setting in your local environment. The languages supported are Chinese, U.S. English, French, German, Japanese, Korean, Polish, Portuguese, and Spanish.

Version dependent. See “Using JCONNECT_ VERSION”.

LANGUAGE_ CURSOR

Determines that jConnect uses “language cursors” instead of “protocol cursors.” See “Cursor performance”.

False

LITERAL_PARAMS

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

NEWPASSWORD

Specifies the new password used in password expiration handling.

Null

PACKETSIZE

Identifies the network packet size. If you are using Adaptive Server 15.0 or later, Sybase recommends that you do not set this property and allow jConnect and Adaptive Server to select the network packet size that is appropriate for your environment.

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

PROMPT_FOR_ NEWPASSWORD

Specifies whether to perform a transparent password change or to prompt for the new password. Values:

• True – prompts you to manually set the new password.

• False – jConnect checks the value of NEWPASSWORD and, if it is not null, uses this value to replace the expired password.

False

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 is encountered. This behavior can be used when a client has calls execute() and the timeout occurs because of a deadlock (for example, trying to read from a table that is currently being updated in another transaction). The default value is false.

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 a high availability (HA) failover session. See “Implementing high availability failover support”.

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

RETRY_WITH_NO_ ENCRYPTION

Allows server to retry logging in using clear text passwords.

When both ENCRYPT_PASSWORD and RETRY_WITH_NO_ENCRYPTION properties are set to true, jConnect first logs in using the encrypted password. If login fails, jConnect logs in using the clear text password. For more information about password encryption, see “Using password encryption”.

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.

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

SERVER_INITIATED_ TRANSACTIONS

Allows the server to control transactions. By default the property is set to true and jConnect lets the server start and control transactions by using the Transact-SQL command set chained on. If set to false, the transactions are started and controlled by jConnect by using the Transact-SQL command begin tran. Sybase recommends that you allow the server to control the transactions.

True

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 SQL Anywhere.

None

SERVERTYPE

When connected to OpenSwitch set this property to “OSW.” This allows jConnect to send certain instructions to OpenSwitch that allows OpenSwitch to remember initial connection settings for example, isolation level, textsize, quoted identifier and autocommit when OpenSwitch redirects a connection to a different server instance.

None

SERVICE_ PRINCIPAL_NAME

Used when establishing a Kerberos connection to Adaptive Server. 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 “Using TDS tunnelling”.

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.

Null

TEXTSIZE

Allows you to set the text size. By default Adaptive Server and SQL Anywhere allow 32,627 bytes to be read from an image or text column. If you have the jConnect mda tables installed, jConnect changes that value to 2GB. However setting this value when connected to OpenSwitch allows the connection to remember the setting when OpenSwitch redirects a connection to a different server instance.

2GB

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

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