The following connection option descriptions are listed alphabetically by the GUI name that appears on the driver Setup dialog box. The connection string attribute name, along with its short name, is listed immediately underneath the GUI name. For example:
In most cases, the GUI name and the attribute name are the same; however, some exceptions exist. If you need to look up an option by its connection string attribute name, please refer to the alphabetical table of connection string attribute names.
Also, a few connection string attributes, for example, Password, do not have equivalent options that appear on the GUI. They are in the list of descriptions alphabetically by their attribute names.
Table 21-1 lists the connection string attributes supported by the Salesforce driver.
If set to 0 (Disabled), the driver does not work with multi-threaded applications. If using the driver with single-threaded applications, this value avoids additional processing required for ODBC thread-safety standards.
If set to 0 (Disabled), bulk load operations are synchronous. The driver does not return from the function that invoked an operation until the operation is complete or the BulkLoadTimeout period has expired. If the operation times out, the driver returns an error.
If set to 1 (Enabled), bulk load operations are asynchronous. The driver returns from the function that invoked an operation after the operation is submitted to the server. The driver does not verify the completion status of the bulk load operation.
where x is a positive integer that specifies the number of rows to be sent.
If set to 0 (Serial), multiple batches associated with a bulk load operation are processed one at a time.
If set to 1 (Parallel), multiple batches associated with a bulk load operation are processed in parallel. The order in which the batches are processed can vary.
Specifies the number of seconds the driver waits to request bulk operation status. This interval is used by the driver the first time it requests status and for all subsequent status requests. See
“Using DataDirect Bulk Load” for more information.
where x is a positive integer that represents the number of seconds the driver waits before requesting bulk operation status.
Determines when the driver uses bulk load for insert, update, delete, or batch operations. If the
Enable Bulk Load option is set to
True and the number of rows affected by an insert, update, delete, or batch operation exceeds the threshold specified by this option, the driver uses the Salesforce Bulk API to perform the operation.
where x is a positive integer that represents a threshold (number of rows).
If set to 0, the driver always uses bulk load to execute insert, update, delete, or batch operations.
If set to x, the driver only uses bulk load if the
Enable Bulk Load option is set to a value of True and the number of rows to be updated by an insert, update, delete, or batch operation exceeds the threshold. If the operation times out, the driver returns an error.
where x is a positive integer that represents a number of seconds the driver waits before requesting bulk operation status.
NOTE: This option is primarily used for initial configuration of the driver for a particular user. It is not intended for use with every connection. By default, the driver configures itself and this option is normally not needed. If Config Options is specified on a connection after the initial configuration, the values specified for Config Options must match the values specified for the initial configuration. The preferred method for setting the configuration options for a particular user is through the database configuration file. See
“Database Configuration File” for details.
where key is one of the following values:
AuditColumns,
CustomSuffix,
MapSystemColumnNames,
NumberFieldMapping, or
UppercaseIdentifiers.
AuditColumns: Determines whether the driver includes audit fields, which Salesforce adds to all objects defined in a Salesforce instance, as table columns when it defines the remote data model to relational table mapping.
IsDeletedCreatedById
CreatedDate
LastModifiedById
LastModifiedDate
SystemModestamp
In a typical Salesforce instance, not all users are granted access to the Audit or MasterRecordId columns. If AuditColumns is set to a value other than
None and the driver cannot include the columns requested, the connection fails and the driver generates a SQLException with a SQLState of 08001.
CustomSuffix (Custom objects and fields only): Determines whether the driver includes or strips the "__c" suffix from the table and column names when mapping the remote data model to the relational data model. Salesforce adds the suffix to all custom objects and fields.
MapSystemColumnNames: Determines how the driver maps Salesforce system columns. Valid values for MapSystemColumnNames are:
NumberFieldMapping: Defines how the driver maps fields defined as NUMBER in Salesforce. The Salesforce API uses DOUBLE values to transfer data to and from NUMBER fields, which can cause problems when the precision of the NUMBER field is greater than the precision of a DOUBLE value. Rounding can occur when converting large values to and from DOUBLE. By default, the driver maps smaller fields (precision of 9 or less) to the INTEGER SQL type when the scale of the NUMBER field is 0 and maps all other NUMBER fields to the DOUBLE SQL type to match the type that Salesforce transfers the value to or from the driver. This key can be used to direct the driver to map all NUMBER fields to DOUBLE regardless of the precision of the field.
UppercaseIdentifiers: Defines how the driver maps identifiers. By default, the driver maps all identifier names to uppercase.
If set to 1 (Enabled), the state of connections removed from the connection pool for reuse by an application is reset to the initial configuration of the connection. Resetting the state can negatively impact performance because additional commands must be sent over the network to the server to reset the state of the connection.
If set to 0 (No), the driver uses the current embedded database specified by DatabaseName. If one does not exist, the connection fails.
If set to 1 (ForceNew), the driver deletes the current embedded database specified by
Database and creates a new one at the same location.
If set to 2 (
NotExist), the driver uses the current embedded database specified by DatabaseName. If one does not exist, the driver creates one.
where string is the name of a data source.
prefix is the file name prefix for the embedded database. For example, if Database is set to a value of
JohnQPublic, the embedded database files that are created or loaded have the form
johnqpublic.xxx.
path+prefix is a relative or absolute path appended to the file name prefix. The path defines the directory the driver uses to store the newly created database files or locate the existing database files. For example, if Database is set to a value of
C:\data\db\johnqpublic, the driver either creates or looks for the database johnqpublic.xxx in the directory
C:\data\db. If you do not specify a path, the current working directory is used.
An optional long description of a data source. This description is not used as a runtime connection attribute, but does appear in the ODBC.INI section of the Registry and in the odbc.ini file.
where string is a description of a data source.
Specifies whether the driver can use the bulk load protocol for insert, update, delete, and batch operations. Bulk load can reduce the number of Web service calls used to execute a statement when compared to statements that are executed individually and may improve performance. Whether the driver actually uses bulk load is determined by the
Bulk Load Threshold connection option.
If set to True, the driver can use the bulk load protocol for insert, update, delete, and batch operations.
If set to False, the driver cannot use the bulk load protocol for insert, update, delete, and batch operations.
A semi-colon separated list of connection options and their values. Use this connection option to set the value of hidden connection options that are provided by Progress customer support. You can include any valid connection option in the Extended Options string.
If the Extended Options string contains option values that are also set in the setup dialog or data source, the values of the options specified in the Extended Options string take precedence.
Do not specify the Extended Options connection option in a connection string, or the driver will return an error. Instead, applications should specify the individual hidden connection options in the connection string.
A string consisting of one or more key=value pairs, for example, HostName=
login.salesforce.com;
HiddenOption1=value[;
HiddenOption2=value;]
The number of rows that the driver processes before returning data to the application. Smaller fetch sizes can improve the initial response time of the query. Larger fetch sizes improve overall fetch times at the cost of additional memory.
FetchSize is related to, but different from, WSFetch Size. WS Fetch Size specifies the number of rows of raw data that the driver fetches from the remote data source, while Fetch Size specifies how many of these raw data rows the driver processes before returning data to the application. Processing the data includes converting from the remote data source data type to the driver SQL data type used by the application. If Fetch Size is greater than WS Fetch Size, the driver makes multiple round trips to the data source to get the requested number of rows before returning control to the application.
where x is a positive integer that specifies the number of rows that the driver processes before returning data to the application.
If set to 0, the driver fetches and processes all of the rows of the result before returning control to the application.
where x is any printable character.
For simplicity, avoid using a value that can be in the data, including all alphanumeric characters, the dash(-), the colon(:), the period (.), the forward slash (/), the space character, the single quote (') and the double quote ("). You can use some of these characters as delimiters if all of the data in the file is contained within double quotes.
url is the is the root of the Salesforce URL to which you want to connect.
Suppose you have a Salesforce instance that is configured with a production instance and a sandbox instance. You can specify
login.salesforce.com as the value for the HostName attribute to connect to the production instance or
test.salesforce.com to connect to the sandbox instance:
One or multiple SQL commands to be executed by the driver after it has established the connection to the database and has performed all initialization for the connection. If the execution of a SQL command fails, the connection attempt also fails and the driver returns an error indicating which SQL command or commands failed.
where string is one or multiple SQL commands.
Multiple commands must be separated by semicolons. In addition, if this option is specified in a connection URL, the entire value must be enclosed in parentheses when multiple commands are specified.
Because fetching metadata and generating mapping files can significantly increase the time it takes to connect to Salesforce, the driver caches this information on the client the first time the driver connects on behalf of each user. The cached metadata is used in subsequent connections made by the user instead of re-fetching the metadata from Salesforce. To force the driver to re-fetch the metadata information for a connection, use the InitializationString property to pass the REFRESH SCHEMA SFORCE command in the connection URL. For example:
A string that contains the arguments that are passed to the JVM that the driver is starting. The location of the JVM must be specified on the driver library path. For information on setting the location of the JVM in your environment, see:
When specifying the heap size for the JVM, note that the JVM tries to allocate the heap memory as a single contiguous range of addresses in the application’s memory address space. If the application's address space is fragmented so that there is no contiguous range of addresses big enough for the amount of memory specified for the JVM, the driver fails to load, because the JVM cannot allocate its heap. This situation is typically encountered only with 32-bit applications, which have a much smaller application address space. If you encounter problems with loading the driver in an application, try reducing the amount of memory requested for the JVM heap. If possible, switch to a 64-bit version of the application.
where the string contains arguments that are defined by the JVM. Values that include special characters or spaces must be enclosed in curly braces { } when used in a connection string.
Specifies the CLASSPATH for the Java Virtual Machine (JVM) used by the driver. The CLASSPATH is the search string the JVM uses to locate the Java jar files the driver needs.
where the string specifies the CLASSPATH. Separate multiple jar files by a semi-colon on Windows platforms and by a colon on Linux and UNIX platforms. CLASSPATH values with multiple jar files must be enclosed in curly braces { } when used in a connection string.
install_dir\java\lib\sforce.jar
The number of seconds to keep inactive connections open in a connection pool. An inactive connection is a database session that is not associated with an ODBC connection handle, that is, a connection in the pool that is not in use by an application.
where x is a positive integer that specifies a number of seconds.
If set to x, inactive connections are closed after the specified number of seconds passes.
where string is the relative or fully qualified path of the configuration file used to initialize the driver logging mechanism. If the specified file does not exist, the driver continues searching for an appropriate configuration file as described in "Using Logging" in the
DataDirect Connect Series for ODBC Reference.
The number of seconds the driver waits for a connection to be established before returning control to the application and generating a timeout error. To override the value that is set by this connection option for an individual connection, set a different value in the SQL_ATTR_LOGIN_TIMEOUT connection attribute using the SQLSetConnectAttr() function.
where x is a positive integer that specifies a number of seconds.
If set to x, inactive connections are closed after the specified number of seconds passes.
Specifies the domain part of the Salesforce user id. If Logon Domain is not an empty string, the driver first appends the @ character to the end of the User Name value and then appends the value of Logon Domain.
where string is a valid user ID domain.
Specifies how often, in seconds, the driver checks the maintenance thread. A single maintenance thread is used to enforce minimum and maximum pool sizes in the connection pool. This option is not used as a runtime connection option, but does appear in the ODBC.INI section of the Registry and in the odbc.ini file.
The maximum number of connections allowed within a single connection pool. When the maximum number of connections is reached, no additional connections can be created in the connection pool.
The minimum number of connections that are opened and placed in a connection pool, in addition to the active connection, when the pool is created. The connection pool retains this number of connections, even when some connections exceed their Load Balance Timeout value.
where x is an integer from 1 to 65535.
password is a valid password. The password is case-sensitive.
password+securitytoken is a valid password appended by the security token required to connect to the Salesforce instance, for example,
secretXaBARTsLZReM4Px47qPLOS, where
secret is the password and the remainder of the value is the security token. Both the password and security token are case-sensitive.
server_name is the name of the server or a fully qualified domain name to which you want to connect.
where the port_name is the port number of the server listener. Check with your system administrator for the correct number.
If set to 1, the connection has read-only access. The following commands are the only commands that you can use when a connection if read-only:
If set to 0, the connection is opened for read/write access, and you can use all commands supported by the product.
where x is any printable character.
For simplicity, avoid using a value that can be in the data, including all alphanumeric characters, the dash(-), the colon(:), the period (.), the forward slash (/), the space character, the single quote (') and the double quote ("). You can use some of these characters as delimiters if all of the data in the file is contained within double quotes.
Specifies whether the driver refreshes a dirty cache on the next fetch operation from the cache. A cache is marked as dirty when a row is inserted into or deleted from a cached table or a row in the cached table is updated.
If set to 1 (Enabled), a dirty cache is refreshed when the cache is referenced in a fetch operation. The cache state is set to initialized if the refresh succeeds.
If set to 0 (Disabled), a dirty cache is not refreshed when the cache is referenced in a fetch operation.
An error message or warning can occur if an ODBC call causes a conversion error, or if an error occurs during code page conversions to and from the database or to and from the application. The error or warning generated is
Code page conversion error encountered. In the case of parameter data conversion errors, the driver adds the following sentence:
Error in parameter x, where
x is the parameter number. The standard rules for returning specific row and column errors for bulk operations apply.
Specifies the security token required to make a connection to a Salesforce instance that is configured for a security token. If a security token is required and you do not supply one, the driver returns an error indicating that an invalid user or password was supplied. Contact your Salesforce administrator to find out if a security token is required.
where string is the value of the security token assigned to the user.
Optionally, you can specify the security token in the Password option by appending the security token to the password, for example,
secretXaBARTsLZReM4Px47qPLOS, where
secret is the password and the remainder of the value is the security token. Do not specify the security token in both options.
where the port_name is the port number of the server listener. Check with your system administrator for the correct number.
Specifies whether the driver’s SQL engine runs in the same 32-bit process as the driver (direct mode) or runs in a process that is separate from the driver (server mode). You must be an administrator to modify the server mode configuration values, and to start or stop the SQL engine service.
If set to 0 (Direct), the SQL engine runs in direct mode. The driver and its SQL engine run in a single process within the same JVM.
If set to 1 (Server), the SQL engine runs in server mode. The SQL engine operates in a separate process from the driver within its own JVM. You must start the SQL Engine service before using the driver (see
“Starting the SQL Engine Server” for more information). Multiple drivers on different clients can use the same service.
where x is a positive integer that defines the maximum number of Web service calls the driver can make when executing any single SQL statement or metadata query.
If set to 0, there is no limit.
If set to x, the driver uses this value to set the maximum number of Web service calls on a single connection that can be made when executing a SQL statement. This limit can be overridden by changing the STMT_CALL_LIMIT session attribute using the ALTER SESSION statement. For example, the following statement sets the statement call limit to 10 Web service calls:
If set to 1 (ErrorAlways), the driver returns an error if the maximum Web service call limit is exceed.
If set to 2 (
ReturnResults), the driver returns any partial results it received prior to the call limit being exceeded. The driver generates a warning that not all of the results were fetched.
If set to 1 - Ignore, the data source does not support transactions and the driver always operates in auto-commit mode. Calls to set the driver to manual commit mode and to commit transactions are ignored. Calls to rollback a transaction cause the driver to return an error indicating that no transaction is started. Metadata indicates that the driver supports transactions and the ReadUncommitted transaction isolation level.
If set to 0 -
No Transactions, the data source and the driver do not support transactions. Metadata indicates that the driver does not support transactions.
The default user ID that is used to connect to your database. Your ODBC application may override this value or you may override it in the logon dialog box or connection string.
where userid is a valid user ID with permissions to access the database.
where x is a positive integer from 1 to 2000 that defines a number of rows.
If set to 0, the driver attempts to fetch up to a maximum of 2000 rows. This value typically provides the maximum throughput.
If set to x, the driver attempts to fetch up to a maximum of the specified number of rows. Setting the value lower than 2000 can reduce the response time for returning the initial data. Consider using a smaller WSFetch Size for interactive applications only.
0 (up to a maximum of 2000 rows)
where x is a positive integer.
If set to 0, the driver does not retry timed-out requests after the initial unsuccessful attempt.
If set to x, the driver retries the timed-out request the specified number of times.
where x is a positive integer that defines the number of seconds the driver waits for a response to a Web service request.
If set to 0, the driver waits indefinitely for a response; there is no timeout.
If set to x, the driver uses the value as the default timeout for any statement created by the connection.
If a Select request times out and WSRetry Count is set to retry timed-out requests, the driver retries the request the specified number of times.