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.
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 11-1 lists the connection string attributes supported by the SQL Server Wire Protocol driver.
|
IANAAppCodePage (IACP)
UNIX ONLY |
|
A list of alternate database servers to which the driver tries to connect if the primary database server is unavailable. Specifying a value for this option enables connection failover for the driver. The value you specify must be in the form of a string that defines the physical location of each alternate server. All of the other required connection information for each alternate server is the same as what is defined for the primary server connection.
The following Alternate Servers value defines two alternate database servers for connection failover:
AlternateServers=(HostName=SqlsServer:PortNumber=1433:Database=Sqlsdb1,
HostName=255.201.11.24:PortNumber=1434:Database=Sqlsdb2)
HostName=255.201.11.24:PortNumber=1434:Database=Sqlsdb2)
Determines how the driver reports results that are generated by database triggers (procedures that are stored in the database and executed, or fired, when a table is modified). For Microsoft SQL Server 2005 and higher, this includes triggers that are fired by Data Definition Language (DDL) events.
If set to 1 (Enabled), the driver returns all results, including results that are generated by triggers. Multiple trigger results are returned one at a time. You can use the SQLMoreResults function to return individual trigger results. Warnings and errors are reported in the results as they are encountered.
|
■
|
|
■
|
When set to 0, the only result that is returned is the update count that is generated by the statement that was executed (if no errors occurred). Although trigger results are ignored, any errors and warnings that are generated by the trigger are reported. If errors are reported, the update count is not reported.
When set to 1 (Enabled), the driver uses ANSI-defined behaviors for handling NULL comparisons, character data padding, warnings, and NULL concatenation. If the driver appears to be truncating trailing blank spaces, this attribute should be set to no.
where string is your application name.
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.
Specifies the method the driver uses to authenticate the user to the server when a connection is established. If the specified authentication method is not supported by the database server, the connection fails and the driver generates an error.
If set to 1 (Encrypt Password), the driver sends the user ID in clear text and an encrypted password to the server for authentication.
If set to 4 (Kerberos Authentication), the driver uses Kerberos authentication. This method supports both Windows Active Directory Kerberos and MIT Kerberos environments.
To connect to SQL Server, users must supply the Windows User Id, Password, and, in some cases, Domain to the driver. Note that NTLM single sign on is supported only on Windows. The number of rows that the driver sends to the database at a time during bulk operations. This value applies to all methods of bulk loading.
where x is a positive integer that specifies the number of rows to be sent.
-1 | 0 | x
where x is an integer that specifies the number of KB.
If set to -1, all binary data, regardless of size, is written to the bulk data file, not to an external file.
If set to 0, all binary data, regardless of size, is written to an external file, not the bulk data file. A reference to the external file is written to the bulk data file.
If set to x, any binary data exceeding this specified number of KB is written to an external file, not the bulk data file. A reference to the external file is written to the bulk data file.
-1 | 0 | x
where x is an integer that specifies the number of KB.
If set to -1, all character data, regardless of size, is written to the bulk data file, not to an external file.
If set to 0, all character data regardless of size, is written to an external file, not the bulk data file. A reference to the external file is written to the bulk data file.
If set to x, any character data exceeding this specified number of KB is written to an external file, not the bulk data file. A reference to the external file is written to the bulk data file.
0 | x
where x is a positive integer representing the cumulative total of the Bulk Options values.
If set to x, the values represented by x are enabled.
NOTE: The cumulative value of the options is only used in a connection string with the connection string attribute, BulkLoadOptions. On the Bulk tab of the driver Setup dialog, the individual options are enabled by selecting the appropriate check box.
|
■
|
Fire Triggers - Causes the server to fire the insert triggers for rows being inserted into the database. Value=32.
|
|
■
|
Keep Identity - Preserves source identity values. When not enabled, identity values are assigned by the destination. Value=1.
|
|
■
|
Keep Nulls - Preserves null values in the destination table regardless of the settings for default values. When not enabled, null values are replaced by column default values, where applicable. Value=64.
|
|
■
|
Table Lock - Assigns a table lock for the duration of the bulk copy operation. Other applications are not permitted to update the table during the copy operation. When not enabled, the default bulk locking mechanism (row or table) specified by the table lock on bulk load server option is used. Value=2.
|
If you wanted to enable Check Constraints (16), Fire Triggers (32), and Keep Identity (1) in a connection string, you would add the values together:
To enable these options on the Bulk tab of the driver Setup dialog, you would simply select the check box for each one.
Determines whether the state of connections that are removed from the connection pool for reuse by the application is reset to the initial configuration of the connection.
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.
The number of times the driver retries connection attempts to the primary database server, and if specified, alternate servers until a successful connection is established.
This option and the Connection Retry Delay connection option, which specifies the wait interval between attempts, can be used in conjunction with failover.
0 | x
where x is a positive integer from 1 to 65535.
If set to x, the driver retries connection attempts the specified number of times. If a connection is not established during the retry attempts, the driver returns an error that is generated by the last server to which it tried to connect.
The number of seconds the driver waits between connection retry attempts when Connection Retry Count is set to a positive integer.
This option and the Connection Retry Count connection option can be used in conjunction with failover.
0 | x
where x is a positive integer from 1 to 65535.
If set to x, the driver waits the specified number of seconds between connection retry attempts.
where string is the name of a data source.
where database_name is the name of a valid database.
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.
DomainTo connect to SQL Server, users must supply the Windows User Id, Password, and, in some cases, domain to the driver. NTLM single sign on is not supported.
where string is a valid Windows domain for the user specified by LoginId. This attribute applies only when Authentication Mode is set to 9.
If set to 1 (Enabled), the driver uses the database bulk load protocol when an application executes an INSERT with multiple rows of parameter data. If the protocol cannot be used, the driver returns a warning.
If set to 1 (Enabled), Microsoft SQL Server enforces ANSI rules regarding quotation marks. Double quotation marks can only be used for identifiers, such as column and table names. Character strings must be enclosed in single quotation marks, for example:
If set to no (Disabled), applications that use quoted identifiers encounter errors when they generate SQL statements with quoted identifiers.
The method the driver uses to encrypt data sent between the driver and the database server. If the specified encryption method is not supported by the database server, the connection fails and the driver returns an error.
If set to 1 (SSL), data is encrypted using SSL. If the server supports protocol negotiation, the driver and server negotiate the use of TLS v1, SSL v3, or SSL v2 in that order.
If set to 6 (RequestSSL) - The login request and data are encrypted using SSL if the server is configured for SSL. If the server is not configured for SSL, an unencrypted connection is established.
If set to 7 (LoginSSL) - The login request is encrypted using SSL regardless of whether the server is configured for SSL. The data is encrypted using SSL if the server is configured for SSL, and the data is unencrypted if the server is not configured for SSL.
NOTE: The driver must use the server-specified packet size when using SSL encryption. If SSL is used, any value set for the Packet Size connection option is ignored.
This option can only be set to 1 when Authentication Method is set to 1.
Determines whether the driver fails the entire failover process or continues with the process if errors occur while trying to reestablish a lost connection.
The Alternate Servers option specifies one or multiple alternate servers for failover and is required for all failover methods.
If set to 0 (Non-Atomic), the driver continues with the failover process and posts any errors on the statement on which they occur.
If set to 1 (Atomic) the driver fails the entire failover process if an error is generated as the result of anything other than executing and repositioning a Select statement. If an error is generated as a result of repositioning a result set to the last row position, the driver continues with the failover process, but generates a warning that the Select statement must be reissued.
If set to 2 (Atomic Including Repositioning), the driver fails the entire failover process if any error is generated as the result of restoring the state of the connection or the state of work in progress.
If set to 3 (Disable Integrity Check), the driver does not verify that the rows that were restored during the failover process match the original rows. This value applies only when Failover Mode is set to 2 (Select).
The Alternate Servers option specifies one or multiple alternate servers for failover and is required for all failover methods.
If set to 1 (Extended Connection), the driver provides failover protection for new and lost connections, but not any work in progress.
If set to 2 (Select), the driver provides failover protection for new and lost connections. In addition, it preserves the state of work performed by the last Select statement executed.
Specifies whether the driver tries to connect to the primary and an alternate server at the same time.
This attribute applies only when Failover Mode is set to 1 (Extended Connection) or 2 (Select) and at least one alternate server is specified.
The Alternate Servers option specifies one or multiple alternate servers for failover and is required for all failover methods.
If set to 0 (Disabled), the driver tries to connect to an alternate server only when failover is caused by an unsuccessful connection attempt or a lost connection. This value provides the best performance, but your application typically experiences a short wait while the failover connection is attempted.
If set to 1 (Enabled), the driver tries to connect to the primary and an alternate server at the same time. This can be useful if your application is time-sensitive and cannot absorb the wait for the failover connection to succeed.
Determines whether the driver returns column values with the timestamp with time zone data type as the ODBC data type SQL_TYPE_TIMESTAMP or SQL_VARCHAR.
If set to 1 (Enabled), the driver returns column values with the timestamp with time zone data type as the ODBC type SQL_TYPE_TIMESTAMP. The time zone information in the fetched value is truncated. Use this value if your application needs to process values the same way as TIMESTAMP columns.
If set to 0 (Disabled), the driver returns column values with the timestamp with time zone data type as the ODBC data type SQL_VARCHAR. Use this value if your application requires the time zone information in the fetched value.
Determines whether the driver returns column values with the time data type as the ODBC data type SQL_TYPE_TIME or SQL_TYPE_TIMESTAMP.
If set to 1 (Enabled), the driver returns column values with the time data type as the ODBC data type SQL_TYPE_TIME. The fractional seconds portion of the value is truncated.
If set to 0 (Disabled), the driver returns column values with the time data type as the ODBC data type SQL_TYPE_TIMESTAMP. The fractional seconds portion of the value is preserved. Time columns are not searchable when they are described and fetched as timestamp
NOTE: When returning time with fractional seconds data as SQL_TYPE_TIMESTAMP, the Year, Month and Day parts of the timestamp must be set to zero.
Specifies the character that the driver will use to delimit the field entries in a bulk load data file.
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.
NOTE: The Bulk Load Field Delimiter character must be different from the Bulk Load Record Delimiter.
The name of the GSS client library that the driver uses to communicate with the Key Distribution Center (KDC).
The driver uses the path defined by the PATH environment variable for loading the specified client library.
native | client_library
where client_library is a GSS client library installed on the client.
If set to client_library, the driver uses the specified GSS client library.
IP_address is the IP address of the server to which you want to connect. Specify this address as: IP_address. For example, you can enter 199.226.224.34.
The IP address can be specified in either IPv4 or IPv6 format, or a combination of the two. See “Using IP Addresses” for details about these formats.
named_server is the named server address of the server to which you want to connect. Specify this address as: named_server. For example, you can enter SSserver.
named_instance is a named instance of Microsoft SQL Server. Specify this address as: server_name\instance_name. If only a server name is specified with no instance name, the driver uses the default instance on the server.
A host name for certificate validation when SSL encryption is enabled (Encryption Method=1) and validation is enabled (Validate Server Certificate=1). This option provides additional security against man-in-the-middle (MITM) attacks by ensuring that the server the driver is connecting to is the server that was requested.
where the host_name is the host name specified in the certificate. Consult your SSL administrator for the correct value.
If set to a host name, the driver examines the subjectAltName values included in the certificate. If a dnsName value is present in the subjectAltName values, then the driver compares the value specified for Host Name In Certificate with the dnsName value. The connection succeeds if the values match. The connection fails if the Host Name In Certificate value does not match the dnsName value.
If no subjectAltName values exist or a dnsName value is not in the list of subjectAltName values, then the driver compares the value specified for Host Name In Certificate with the commonName part of the Subject name in the certificate. The commonName typically contains the host name of the machine for which the certificate was created. The connection succeeds if the values match. The connection fails if the Host Name In Certificate value does not match the commonName. If multiple commonName parts exist in the Subject name of the certificate, the connection succeeds if the Host Name In Certificate value matches any of the commonName parts.
If set to #SERVERNAME#, the driver compares the host server name specified as part of a data source or connection string to the dnsName or the commonName value.
IANAAppCodePageAn Internet Assigned Numbers Authority (IANA) value. You must specify a value for this option if your application is not Unicode‑enabled or if your database character set is not Unicode. Refer to Chapter 4 “Internationalization, Localization, and Unicode” in the DataDirect Connect Series for ODBC Reference for details.
If the driver does not find an IANAAppCodePage value, the driver uses the default value of 4 (ISO 8859-1 Latin-1).
where IANA_code_page is one of the valid values listed in Chapter 1 “Values for the Attribute IANAAppCodePage” in the DataDirect Connect Series for ODBC Reference. The value must match the database character encoding and the system locale.
A SQL command that is issued immediately after connecting to the database to manage session settings.
NOTE: If the statement fails to execute, the connection fails and the driver reports the error returned from the server.
where SQL_command is a valid SQL command that is supported by the database.
where lang is the language to use for Microsoft SQL Server system messages. This overrides the default language specified for the login on the server. If no language is specified, the connection uses the default language specified for the login on the server.
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.
0 | x
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.
Determines whether the driver uses client load balancing in its attempts to connect to the database servers (primary and alternate). You can specify one or multiple alternate servers by setting the Alternate Servers option.
If set to 1 (Enabled), the driver uses client load balancing and attempts to connect to the database servers (primary and alternate servers) in random order.
If set to 0 (Disabled), the driver does not use client load balancing and connects to each server based on their sequential order (primary server first, then, alternate servers in the order they are specified).
NOTE: This option has no effect unless alternate servers are defined for the Alternate Servers connection option.
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.
-1 | 0 | x
where x is a positive integer that specifies a number of seconds.
If set to -1, the connection request does not time out. The driver silently ignores the SQL_ATTR_LOGIN_TIMEOUT attribute.
If set to 0, the connection request does not time out, but the driver responds to the SQL_ATTR_LOGIN_TIMEOUT attribute.
If set to x, the connection request times out after the specified number of seconds unless the application overrides this setting with the SQL_ATTR_LOGIN_TIMEOUT attribute.
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.
0 | x
where x is an integer from 1 to 65535.
For example, if set to 5, the start-up number of connections in the pool is 5 in addition to the current existing connection.
Determines the number of bytes for each database protocol packet that is transferred from the database server to the client machine. Adjusting the packet size can improve performance. The optimal value depends on the typical size of data that is inserted, updated, or returned by the application and the environment in which it is running. Typically, larger packet sizes work better for large amounts of data. For example, if an application regularly returns character values that are 10,000 characters in length, using a value of 32 (16 KB) typically results in improved performance.
NOTE: The ODBC connection option SQL_PACKET_SIZE provides the same functionality as the Packet Size option; however SQL_PACKET SIZE and the Packet Size option are mutually exclusive. If Packet Size is specified, the driver returns the message Driver Not Capable if an application attempts to call SQL_PACKET_SIZE. If you do not set the Packet Size option, application calls to SQL_PACKET_SIZE are accepted by the driver.
-1 | 0 | x
If set to x, an integer from 1 to 127, the driver uses a packet size that is a multiple of 512 bytes. For example, PacketSize=8 means to set the packet size to 8 * 512 bytes (4096 bytes).
NOTE: IF SSL encryption is used, the driver must use the packet size that is specified by the server. Any value set for this option or the SQL_PACKET_SIZE connect option is ignored if SSL encryption is used.
The password that the application uses to connect to your database. The Password option cannot be specified through the driver Setup dialog box and should not be stored in a data source. It is specified through the Logon dialog box or a connection string.
where pwd is a valid password.
where the port_name is the port number of the server listener. Check with your database administrator for the correct number.
The number of seconds for the default query timeout for all statements that are created by a connection. To override the value set by this connection option for an individual statement, set a different value in the SQL_ATTR_QUERY_TIMEOUT statement attribute on the SQLSetStmtAttr() function.
-1 | 0 | x
where x is a positive integer that specifies a number of seconds.
If set to -1, the query does not time out. The driver silently ignores the SQL_ATTR_QUERY_TIMEOUT attribute.
If set to 0, the query does not time out, but the driver responds to the SQL_ATTR_QUERY_TIMEOUT attribute.
If set to x, all queries time out after the specified number of seconds unless the application overrides this value by setting the SQL_ATTR_QUERY_TIMEOUT attribute.
Specifies the character that the driver will use to delimit the record entries in a bulk load data file.
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.
NOTE: The Bulk Load Record Delimiter character must be different from the Bulk Load Field Delimiter.
Specifies how the driver handles code page conversion errors that occur when a character cannot be converted from one character set to another.
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.
If set to 0 (Ignore Errors), the driver substitutes 0x1A for each character that cannot be converted and does not return a warning or error.
If set to 1 (Return Error), the driver returns an error instead of substituting 0x1A for unconverted characters.
If set to 2 (Return Warning), the driver substitutes 0x1A for each character that cannot be converted and returns a warning.
The directory that contains the truststore file and the truststore file name to be used when SSL is enabled (Encryption Method=1) and server authentication is used. The truststore file contains a list of the valid Certificate Authorities (CAs) that are trusted by the client machine for SSL server authentication. If you do not specify a directory, the current directory is used.
where truststore_directory is the directory where the truststore file is located and filename is the file name of the truststore file.
The password that is used to access the truststore file when SSL is enabled (Encryption Method=1) and server authentication is used. The truststore file contains a list of the Certificate Authorities (CAs) that the client trusts.
NOTE: The truststore and keystore files may be the same file; therefore, they may have the same password.
where truststore_password is a valid password for the truststore file.
Allows your application to use the snapshot isolation level if your Microsoft SQL Server database is configured for Snapshot isolation. Supported only for Microsoft SQL Server 2005 and higher.
See “Using The Snapshot Isolation Level” for details about using the snapshot isolation level.
When set to 1 (Enabled) and your application has the transaction isolation level set to serializable, the application uses the snapshot isolation level.
When set to 0 (Disabled) and your application has the transaction isolation level set to serializable, the application uses the serializable isolation level.
This option is useful for existing applications that set the isolation level to serializable. Using Snapshot Transactions in this case allows you to change to the snapshot isolation level with no or minimum code changes. If developing a new application, you can code it to set the connection attribute SQL_COPT_SS_TXN_ISOLATION to the value SQL_TXN_SS_SNAPSHOT.
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.
Determines whether the driver validates the certificate that is sent by the database server when SSL encryption is enabled (Encryption Method=1). When using SSL server authentication, any certificate sent by the server must be issued by a trusted Certificate Authority (CA). Allowing the driver to trust any certificate returned from the server even if the issuer is not a trusted CA is useful in test environments because it eliminates the need to specify truststore information on each client in the test environment.
If set to 1 (Enabled), the driver validates the certificate that is sent by the database server. Any certificate from the server must be issued by a trusted CA in the truststore file. If the Host Name In Certificate option is specified, the driver also validates the certificate using a host name. The Host Name In Certificate option provides additional security against man-in-the-middle (MITM) attacks by ensuring that the server the driver is connecting to is the server that was requested.
If set to 0 (Disabled), the driver does not validate the certificate that is sent by the database server. The driver ignores any truststore information specified by the Trust Store and Trust Store Password options.
where string is the workstation ID.
See “Using the XML Data Type” for further information about the XML data type.
If set to -4 (SQL_LONGVARBINARY), the driver uses the description SQL_LONGVARBINARY for columns that are defined as the XML data type.
If set to -10 (SQL_WLONGVARCHAR), the driver uses the description SQL_WLONGVARCHAR for columns that are defined as the XML data type.