Connecting to a Data Source Using a Connection String

If you want to use a connection string for connecting to a database, or if your application requires it, you must specify either a DSN (data source name), a File DSN, or a DSN-less connection in the string. The difference is whether you use the DSN=, FILEDSN=, or the DRIVER= keyword in the connection string, as described in the ODBC specification. A DSN or FILEDSN connection string tells the driver where to find the default connection information. Optionally, you may specify attribute=value pairs in the connection string to override the default values stored in the data source.

The DSN connection string has the form:

DSN=data_source_name[;attribute=value[;attribute=value]...] 

The FILEDSN connection string has the form:

FILEDSN=filename.dsn[;attribute=value[;attribute=value]...] 

The DSN-less connection string specifies a driver instead of a data source. All connection information must be entered in the connection string because there is no data source storing the information.

The DSN-less connection string has the form:

DRIVER=[{]driver_name[}][;attribute=value[;attribute=value]
...] 

Table 8-1 gives the long and short names for each attribute, as well as a description. You can specify either long or short names in the connection string. Connection string attribute names are the same as the option names on the driver Setup dialog box tabs unless otherwise noted. The connection string attribute name does not have spaces between the words. For example, the connection string attribute name ApplicationUsingThreads is equivalent to the option name Application Using Threads.

The defaults listed in the table are initial defaults that apply when no value is specified in either the data source definition or in the connection string. If you specified a value for the attribute when configuring the data source, that value is the default.

An example of a DSN connection string with overriding attribute values for Sybase is:

DSN=SYB TABLES;DB=PAYROLL;UID=JOHN;PWD=XYZZY 

A FILEDSN connection string is similar except for the initial keyword:

FILEDSN=SYB.dsn;DB=PAYROLL;UID=JOHN;PWD=XYZZY 

A DSN-less connection string must provide all necessary connection information:

DRIVER=DataDirect Sybase Wire Protocol; 
NA=123.456.78.90, 5000;NLN=Winsock; 
DB=SYBACCT;UID=JOHN;PWD=XYZZY 
 



  
 

Table 8-1.  Sybase Wire Protocol Connection String Attributes 


  
    
 

Attribute


    
 

Description



  
    
 

AlternateServers	 (ASRV)


    
 

A list of alternate database servers to which the driver will try to connect if the primary database server is unavailable. Specifying a value for this connection string attribute enables connection failover for the driver. See "Using Connection Failover" for a discussion of connection failover.

 

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.

 

For the Sybase Wire Protocol driver, you must specify the network address of each alternate database server or the section in the Interfaces file that contains the network connection information for the Sybase database server you want to access (InterfacesFileServerName). The string has the format:

({NetworkAddress=addressvalue | 
InterfacesFileServerName=sectionvalue}[, . . .]) 

 

NetworkAddress and InterfacesFileServerName can be used in the same string. The following example Alternate Servers values define four alternate database servers for connection failover:

(InterfacesFileServerName=Accounting, 
NetworkAddress=\\MySybaseASE\Query, 
NetworkAddress="255.125.1.11, 4200", 
NetworkAddress="SybaseASE2, 4200") 



  
    
 

AlternateServers	 (ASRV)
cont.


    
 

Notice in the last two alternates that the network address is enclosed in quotation marks. This is because they contain commas and might be mistaken for the next alternate server in the list.

 

IMPORTANT: The alternate database servers specified for the Sybase Wire Protocol driver must be using the same network protocol as specified for the primary database server. On UNIX and Linux, only TCP/IP is supported; on Windows, the driver supports both Named Pipes and TCP/IP. 

 

NOTE: The Alternate Servers option and the HA Failover Server Connection Information option are mutually exclusive. If you enter a value for the Alternate Servers, HA Failover Server Connection Information is not available. 

 

See "MTS Support" for information about other connection options that you can set for this feature.



  
    
 

ApplicationName (APP)


    
 

The name used by Sybase to identify your application.



  
    
 

ApplicationUsingThreads (AUT)


    
 

ApplicationUsingThreads={0 | 1}. Determines whether the driver works with multi-threaded applications. 

 

When set to 1 (the initial default), the driver is thread-safe and is ensured to work with multi-threaded applications. 

 

When using the driver with single-threaded applications, you can set this option to 0 to avoid additional processing required for ODBC thread-safety standards.   

 

This attribute can affect performance. See "Performance Considerations" for details.



  
    
 

ArraySize (AS)


    
 

The number of rows the driver retrieves from the server for a fetch. This is not the number of rows given to the user. 

 

The initial default is 50 rows.

 

This attribute can affect performance. See "Performance Considerations" for details.

 

The equivalent Setup dialog box option is Fetch Array Size.



  
    
 

Authentication
Method (AM)


    
 

AuthenticationMethod={0 | 1 | 4}. Determines the security method the driver uses to authenticate the user to the server when a connection is established. 

 

When set to 0 (the initial default), the driver sends the user ID and password in clear text to the server for authentication.

 

When set to 1, the driver sends the user ID in clear text and an encrypted password to the server for authentication. Note that the Sybase server must have password encryption enabled (Sybase 12.0 and higher). The specific encryption used is the algorithm required by the Sybase server and is completely implemented within the driver. This encryption capability in the driver is used only for the password at connect time and only when sending it across the network to the server.

 

When set to 4, the driver uses Kerberos authentication. This method supports both Windows Active Directory Kerberos and MIT Kerberos environments.

 

If the specified authentication method is not supported by the database server, the connection fails and the driver generates an error.

 

See "Using Security" for a general description of authentication and its configuration requirements.



  
    
 

Charset (CS)


    
 

The name of a character set. This character set must be installed on the Sybase server. The default is the setting on the Sybase server. For this driver to return Unicode SQL types, this attribute must be set to UTF-8 and you must be connected to a Sybase 12.5 or higher server. Refer to the Sybase server documentation for a list of valid character set names.

 

For example, if your client needs to receive data in iso-8859-1 from a non-Unicode Sybase server, you would specify a value of iso_1 for Charset.

 

This setting affects the Sybase server only. Charset is not a substitute for the IANAAppCodePage option. See IANAAppCodePage (IACP) for details.



  
    
 

ConnectionRetryCount (CRC)


    
 

Specifies the number of times the driver tries to connect to the primary server, and if configured, to the alternate servers after the initial unsuccessful attempt. See "Using Connection Retry" for more information about this feature.

 

Valid values are integers from 0 to 65535. When set to 0 (the initial default), the driver does not try to connect after the initial unsuccessful attempt.

 

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.

 

This attribute and the ConnectionRetryDelay connection string attribute, which specifies the wait interval between attempts, can be used in conjunction with connection failover.

 

See "MTS Support" for a discussion of connection failover and for information about other connection string attributes that you can set for this feature.



  
    
 

ConnectionRetryDelay (CRD)


    
 

Specifies the number of seconds that the driver waits after the initial unsuccessful connection attempt before retrying a connection to the primary server and, if specified, to the alternate servers. 

 

Valid values are integers from 0 to 65535. The initial default is 3 (seconds). When set to 0, there is no delay between retries.

 

NOTE: This attribute has no effect unless the ConnectionRetryCount connection string attribute is set to an integer value greater than 0.

 

This attribute and the ConnectionRetryCount connection string attribute, which specifies the number of times the driver tries to connect after the initial unsuccessful attempt, can be used in conjunction with connection failover.    

 

See "MTS Support" for a discussion of connection failover and for information about other connection string attributes that you can set for this feature.



  
    
 

CursorCacheSize (CCS)


    
 

The number of connections that the connection cache can hold. To set the connection cache, you must set the SelectMethod attribute to 1. Increasing the connection cache may increase performance of some applications but requires additional database resources.

 

The initial default is 1.

 

The equivalent Setup dialog box option is Connection Cache Size.



  
    
 

Database (DB)


    
 

The name of the database to which you want to connect.



  
    
 

DataSourceName (DSN)


    
 

A string that identifies a Sybase data source configuration. Examples include Accounting or Sys10-Serv1.



  
    
 

DefaultLongDataBuffLen (DLDBL)


    
 

An integer factor value that specifies, in 1024-byte multiples, the maximum length of data fetched from Long/LOB columns. The value must be in multiples of 1024 (for example, 1024, 2048). You need to increase the default value if the total size of any Long data exceeds 1 MB. This value is multiplied by 1024 to determine the total maximum length of fetched data. For example, if you enter a value of 2048, the maximum length of data would be 1024 x 2048, or 2097152 (2 MB).

 

This attribute also applies to binding long parameters in chunks. The driver truncates any data passed in a Long/LOB SQL_DATA_AT_EXEC parameter to the size specified.

 

The initial default is 1024.

 

This attribute can affect performance. See "Performance Considerations" for details.

 

The equivalent Setup dialog box option is Default Buffer Size for Long/LODB Columns (in KB).



  
    
 

DistributedTransaction
Model (DTM)

 




    
 

DistributedTransactionModel={XA Protocol | Native OLE}. Determines which model is used for distributed transaction support. The initial default is XA Protocol.



  
    
 

EnableDescribe
Param (EDP)


    
 

EnableDescribeParam={0 | 1}. Determines whether the ODBC API function SQLDescribeParam is enabled.

 

When set to 0 (the initial default), SQLDescribeParam is disabled.

 

When set to 1, SQLDescribeParam is enabled, which allows an application to describe parameters in SQL statements and in stored procedure calls. To use this option, OptimizePrepare must be set to 0 or 1, and the SQL statement must not include long parameters. This attribute must be set to 1 when using Microsoft Remote Data Objects (RDO) to access data.



  
    
 

EnableQuoted
Identifiers (EQI)


    
 

EnableQuotedIdentifiers={0 | 1}. Enables quoted identifiers.

 

When set to 1, 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:

SELECT "au_id" 
FROM "authors" 
WHERE "au_lname" = 'O''Brien' 

 

When set to 0 (the initial default), applications that use quoted identifiers encounter errors when they generate SQL statements with quoted identifiers.



  
    
 

Encryption
Method (EM)


    
 

EncryptionMethod={0 | 1}. Specifies the method the driver uses to encrypt data sent between the driver and the database server. 

 

When set to 0 (the default), data is not encrypted.

 

When set to 1, data is encrypted using SSL.

 

If the specified encryption method is not supported by the database server, the connection fails and the driver returns an error.

 

See "Using Security" for a general description of encryption and its configuration requirements.

 

This attribute can affect performance. See "Performance Considerations" for details.



  
    
 

FailoverNetworkAddress (FNA)

 




    
 

The address of the High Availability (HA) Failover server to be used in the event of a connection loss. The driver detects the dropped connection and automatically reconnects to the HA Failover server specified by this attribute. This attribute is valid only for Sybase 12 and higher servers that have the High Availability Failover feature enabled.

 

See the NetworkAddress (NA) attribute for an explanation of valid values.

 

NOTE: The HA Failover Server Connection Information option and the Alternate Servers option are mutually exclusive. If you enter a value for the HA Failover Server Connection Information option, the Alternate Servers option is not available.



  
    
 

GSSClient (GS)


    
 

Specifies the GSS client library that the driver uses to communicate with the Key Distribution Center (KDC). The initial default is native, indicating that the driver uses the GSS client that ships with the operating system. The driver uses the standard path for loading the specified client library.

 

See "Using Security" for a general description of authentication and its configuration requirements.

 

 



  
    
 

HostNameInCertificate (HNIC)


    
 

Specifies whether the driver validates the host name contained in the certificate returned by the database server on systems using SSL. The host name is established by the SSL administrator. If no value is specified for HostNameInCertificate, the driver does not check the host name in the server certificate. The value of HostNameInCertificate is ignored if ValidateServerCertificate is set to 0 or if EncryptionMethod does not specify SSL.

 

If a value is specified for HostNameInCertificate, 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 HostNameInCertificate with the dnsName value. The connection succeeds if the values match. The connection fails if the HostNameInCertificate 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 HostNameInCertificate 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 HostNameInCertificate value does not match the commonName. If multiple commonName parts exist in the Subject name of the certificate, the connection succeeds if the HostNameInCertificate value matches any of the Common Name parts.

 

See "Using Security" for a general description of encryption and its configuration requirements.

 

If the value specified for HostNameInCertificate is the special value #SERVERNAME#, then the driver compares the NetworkAddress (NA) attribute value specified as part of a data source or connection string to the dnsName value or the commonName.



  
    
 

IANAAppCodePage (IACP)

 




    
 

For a list of valid values for this attribute, refer to "Values for the Attribute IANAAppCodePage" in the DataDirect Connect for ODBC and Connect XE for ODBC Reference. You need to specify a value for this attribute if your application is not Unicode-enabled and/or if your database character set is not Unicode (refer to "Internationalization, Localization, and Unicode" in the DataDirect Connect for ODBC and Connect XE for ODBC Reference for details). The value you specify must match the database character encoding and the system locale.

 

Both this driver and the Driver Manager check for the value of IANAAppCodePage in the following order:


 
In the connection string
 
In the Data Source section of the system information file (odbc.ini)
 
In the ODBC section of the system information file (odbc.ini)

 

If no IANAAppCodePage value is found, the driver uses the default value of 4 (ISO 8859-1 Latin-1).

 

This option specifies what the client assumes about incoming data. This is not the same as setting the Charset option for the Sybase server. See Charset (CS) for details.



  
    
 

InitializationString (IS)


    
 

InitializationString={Sybase set commands;...}. Supports the execution of Sybase commands at connect time. Multiple commands must be separated by semicolons.



  
    
 

InterfacesFile (IF)

 




    
 

The path name of the Interfaces file. If you do not specify a value for this attribute, but specify a value for the InterfacesFileServerName attribute, the driver looks for the path name of the Interfaces file in the Registry under HKEY_LOCAL_MACHINE\SOFTWARE\DataDirect\InterfacesFile. If this Registry value is empty, then the driver attempts to open the SQL.INI file found in the same directory as the driver and use it as the Interfaces file.

 

NOTE: When specifying connection information, you specify either a network address or an Interfaces file and server name.



  
    
 

InterfacesFileServerName (IFSN)

 




    
 

The name of the section in the Interfaces file that contains the network connection information for the Sybase server you want to access. The section name typically is the host name of the server that contains the Sybase server you want to access.

 

NOTE: When specifying connection information, you specify either a network address or an Interfaces file and server name.

 

The equivalent Setup dialog box option is Server Name.



  
    
 

Language (LANG)


    
 

The national language. This language must be installed on the Sybase server. 

 

The initial default is English.



  
    
 

LoadBalancing (LB)


    
 

LoadBalancing={0 | 1}. Determines whether the driver uses client load balancing in its attempts to connect to primary and alternate database servers. See "Using Client Load Balancing" for more information.

 

When set to 1, the driver attempts to connect to the database servers in random order. 

 

When set to 0 (the initial default), client load balancing is not used and the driver connects to each database server based on its sequential order (primary server first, then, alternate servers in the order they are specified).

 

NOTE: This attribute has no effect unless alternate servers are defined for the AlternateServers connection string attribute.

 

The LoadBalancing connection string attribute is an optional setting that you can use in conjunction with connection failover. See "MTS Support" for a discussion of connection failover and for information about other connection string attributes that you can set for this feature.



  
    
 

LogonID (UID)


    
 

The default user ID 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.

 

The equivalent Setup dialog box option is User Name.



  
    
 

NetworkAddress (NA)


    
 

Specify an IP address as follows: IP address, port_number. For example, you might enter 199.226.224.34, 5000. If your network supports named servers, you can specify an address as: servername, port_number. For example, you might enter Sybaseserver, 5000.

 

The numeric IP address can be specified in either IPv4 or IPv6 format, or a combination of the two. See "Using IP Addresses" for details concerning these formats.

 

NOTE: When specifying connection information, you specify either a network address or an Interfaces file and server name.



  
    
 





    
 

NetworkLibraryName={Winsock | NamedPipes}. The name of the network library. This specifies which network protocol to use.

 

The initial default is Winsock. 

 

This attribute has no effect on UNIX and Linux; on UNIX and Linux, TCP/IP is used.



  
    
 

OptimizePrepare (OP)


    
 

OptimizePrepare={0 | 1 | 2 | 3}. Determines whether stored procedures are created on the server for calls to SQLPrepare.

 

When set to 0, stored procedures are created for every call to SQLPrepare. This setting can result in decreased performance when processing statements that do not contain parameters.

 

When set to 1 (the initial default), the driver creates stored procedures only if the statement contains parameters. Otherwise, the statement is cached and runs directly at the time of SQLExecute. 

 

When set to 2, stored procedures are never created. The driver caches the statement, executes it directly at the time of SQLExecute, and reports any syntax or similar errors at the time of SQLExecute.

 

When set to 3, stored procedures are never created. This is identical to value 2 except that any syntax or similar errors are returned at the time of SQLPrepare instead of SQLExecute. Use this setting only if you must have syntax errors reported at the time of SQLPrepare.

 

This attribute can affect performance. See "Performance Considerations" for details.

 

The equivalent Setup dialog box option is Prepare Method.



  
    
 

PacketSize (PS)


    
 

PacketSize={-1 | 0 | x}. Determines the number of bytes per packet transferred from the database server to the client machine (Sybase refers to this packet as a network packet). The correct setting of this attribute can improve performance. The optimal value depends on the typical size of data inserted, updated, or retrieved 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 retrieves character values that are 10,000 characters in length, using a value of 32 (16 KB) typically results in improved performance.

 

When set to -1, the driver computes the maximum allowable packet size on the first connection to the data source and saves the value.

 

When set to 0 (the initial default), the driver uses the default packet size as specified in the Sybase server configuration.

 

When set to x, an integer from 1 to 127, the driver uses a packet size represented by x times 512 bytes. For example, PacketSize=6 means to set the packet size to 6 * 512 bytes (3072 bytes).

 

To take advantage of this connection string attribute, you must configure the Sybase server for a maximum packet size greater than or equal to the value you specified for Packet Size times 127. Using the previous example:

sp_configure "max network packet size", 3072 
reconfigure 
Restart Sybase Server 

 

NOTE: The ODBC specification identifies a connect option, SQL_PACKET_SIZE, that offers this same functionality. To avoid conflicts with applications that may set both, the connection string attribute and the ODBC connect option have been defined as mutually exclusive. If PacketSize is specified, you receive the message Driver Not Capable if you attempt to call SQL_PACKET_SIZE. If you do not set PacketSize, then application calls to SQL_PACKET_SIZE are accepted by the driver.

 

This attribute can affect performance. See "Performance Considerations" for details.



  
    
 

Password (PWD)


    
 

A case-sensitive password.



  
    
 




    
 

Password Encryption={0 | 1}. Specifies whether the user's password is encrypted (Sybase ASE version 12.0 and higher).

 

When set to 0 (the initial default), the password is not encrypted.

 

When set to 1, to the driver encrypts the user's password as it is sent to the Sybase server. Note that the Sybase server must have password encryption enabled. The specific encryption used is the algorithm required by the Sybase server and is completely implemented within the driver. This encryption capability in the driver is used only for the password at connect time and only when sending it across the network to the server.



  
    
 

RaiseErrorPosition
Behavior (REPB)


    
 

RaiseErrorPositionBehavior={0 | 1}. Specifies when the error is returned and where the cursor is positioned when raiserror is encountered.

 

When set to 0 (the initial default), raiserror is handled separately from surrounding statements. The error is returned when raiserror is processed via SQLExecute, SQLExecDirect, or SQLMoreResults. The result set is empty.

 

When set to 1 (Microsoft compatible), raiserror is handled with the next statement. The error is returned when the next statement is processed; the cursor is positioned on the first row of the subsequent result set. This could result in multiple raiserrors being returned on a single execute.



  
    
 

ReportCodePage
ConversionErrors (RCCE)


    
 

ReportCodePageConversionErrors={0 | 1 | 2}. Provides flexibility for the way in which the driver returns error or warning messages associated with code page conversion. 

 

When set to 0 (the initial default), if the driver encounters code page conversion errors (a character cannot be converted from one character set to another), it makes a substitution for each character that cannot be converted and does not return a warning or error.

 

Settings 1 and 2 apply both to all ODBC API calls that could cause a conversion error and to all code page conversions to and from the database and to and from the application. The error or warning returned 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 still apply.

 

When set to 1, if the driver encounters code page conversion errors, it returns an error instead of substituting 0x1A for unconverted characters.

 

When set to 2, if the driver encounters code page conversion errors, it substitutes 0x1A for each character that cannot be converted and returns a warning.



  
    
 

SelectMethod (SM)


    
 

SelectMethod={0 | 1}. Determines whether database cursors are used for Select statements. 

 

When set to 0 (the initial default), database cursors are used. In some cases performance degradation can occur when performing large numbers of sequential Select statements because of the amount of overhead associated with creating database cursors.

 

When set to 1, Select statements are run directly without using database cursors, and the data source is limited to one active statement.

 

This attribute can affect performance. See "Performance Considerations" for details.



  
    
 

ServicePrincipalName (SPN)


    
 

The service principal name of the Sybase server that the driver uses with Kerberos authentication. This value has the following form:

 

servicePrincipalName

 

where servicePrincipalName is the service principal name of the Sybase server.

 

If no value is specified for ServicePrincipalName, then the value of NetworkAddress is used as the service principal name. If Kerberos authentication is not used, the value of ServicePrincipalName is ignored.

 

See "Using Security" for a general description of encryption and its configuration requirements.



  
    
 

TightlyCoupled
DistributedTransactions (TCDT)

 





    
 

TightlyCoupledDistributedTransactions={0 | 1}. Determines whether the driver uses tightly coupled distributed transactions when connected to Sybase 12 or higher database.

 

When set to 1 (the initial default), the driver uses this type of transaction and multiple connections within the same distributed transaction obey each other's locks.

 

When set to 0, the overall performance of the driver is better, but multiple connections within the same distributed transaction may hang each other because the connections do not obey each other's locks.

 

This attribute is valid only when the driver is enlisted in a distributed transaction or when it is connected to a Sybase 12 or higher database. Otherwise, this attribute is ignored.



  
    
 

TruncateTimeTypeFractions (TTTF)


    
 

TruncateTimeTypeFractions={0 | 1}. Determines whether the driver sets fractional seconds to zero when converting from SQL_TYPE_TIME to SQL_C_TYPE_TIMESTAMP, SQL_C_CHAR, or SQL_C_WCHAR.

 

When set to 1, the fractional seconds are converted to zero.

 

NOTE: This only applies to the Sybase 12.5.1 and higher Time data type.

 

The initial default is 0.



  
    
 

TrustStore (TS)


    
 

The path that specifies the location of the truststore file. The truststore file contains a list of the valid Certificate Authorities (CAs) that are trusted by the client machine for SSL server authentication.

 

See "Using Security" for a general description of encryption and its configuration requirements.

 

 



  
    
 

TrustStorePassword (TSP)


    
 

The password required to access the truststore.

 

See "Using Security" for a general description of encryption and its configuration requirements.

 

 



  
    
 

ValidateServerCertificate (VSC)


    
 

ValidateServerCertificate={0 | 1}. Determines whether the driver validates the security certificate of the server as part of the SSL authentication handshake.

 

When set to 0, the driver does not validate the certificate.

 

	When set to 1 (the initial default), the driver validates the certificate.

 

See "Using Security" for a general description of encryption and its configuration requirements.

 

 



  
    
 

WorkstationID (WKID)


    
 

The workstation ID used by the client.



  
    
 

XAOpenStringParameters (XAOSP)

 




    
 

The name of trace files. Use the syntax -Ltrace_filename, where trace_filename specifies the name of two trace files that will be created. The first trace file will trace all XA call activities and will be named exactly as you specified. The second trace file will contain tracing of any enlistment and unenlistment procedures and will be named as you specified with a "driver" extension. For example, if you specify XAtrace as the file name, the driver will create two trace files-XAtrace and XAtrace.driver.