SQLDriverConnect
The Microsoft® SQL Server™ ODBC driver and the ODBC driver manager recognize the following SQLDriverConnect connection string keywords.
| Keyword | Description |
|---|---|
| Address | Network address of the server running an instance of SQL Server. Address is usually the network name of the server, but can be other names such as a pipe, or a TCP/IP port and socket address. For more information, see Managing Clients. |
| AnsiNPW | When yes, the driver uses ANSI-defined behaviors for handling NULL comparisons, character data padding, warnings, and NULL concatenation. When no, ANSI defined behaviors are not exposed. For more information about ANSI NPW behaviors, see Effects of SQL-92 Options. |
| APP | Name of the application calling SQLDriverConnect (optional). If specified, this value is stored in the master.dbo.sysprocesses column program_name and is returned by sp_who and the Transact-SQL APP_NAME function. |
| AttachDBFileName | Name of the primary file of an attachable database. Include the full path and escape any \ characters if using a C character string variable:
AttachDBFileName=c:\\MyFolder\\MyDB.mdf This database is attached and becomes the default database for the connection. To use AttachDBFileName you must also specify the database name in either the SQLDriverConnnect DATABASE parameter or the SQL_COPT_CURRENT_CATALOG connection attribute. If the database was previously attached, SQL Server will not reattach it; it will use the attached database as the default for the connection. |
| AutoTranslate | When yes, ANSI character strings sent between the client and server are translated by converting through Unicode to minimize problems in matching extended characters between the code pages on the client and the server:
Client SQL_C_CHAR data sent to a SQL Server char, varchar, or text variable, parameter, or column is converted from character to Unicode using the client ANSI code page (ACP), then converted from Unicode to character using the ACP of the server. SQL Server char, varchar, or text data sent to a client SQL_C_CHAR variable is converted from character to Unicode using the server ACP, then converted from Unicode to character using the client ACP. These conversions are performed on the client by the SQL Server ODBC driver. This requires that the same ANSI code page (ACP) used on the server be available on the client. These settings have no effect on the conversions that occur for these transfers: Unicode SQL_C_WCHAR client data sent to char, varchar, or text on the server. char, varchar, or text server data sent to a Unicode SQL_C_WCHAR variable on the client. ANSI SQL_C_CHAR client data sent to Unicode nchar, nvarchar, or ntext on the server. Unicode char, varchar, or text server data sent to an ANSI SQL_C_CHAR variable on the client. When no, character translation is not performed. The SQL Server ODBC driver does not translate client ANSI character SQL_C_CHAR data sent to char, varchar, or text variables, parameters, or columns on the server. No translation is performed on char, varchar, or text data sent from the server to SQL_C_CHAR variables on the client. If the client and SQL Server are using different ACPs, then extended characters can be misinterpreted. |
| DATABASE | Name of the default SQL Server database for the connection. If Database is not specified, the default database defined for the login is used. The default database from the ODBC data source overrides the default database defined for the login. The database must be an existing database unless AttachDBFileName is also specified. If AttachDBFileName is also specified, the primary file it points to is attached and given the database name specified by DATABASE. |
| DRIVER | Name of the driver as returned by SQLDrivers. The keyword value for the SQL Server ODBC driver is "{SQL Server}". The braces are required when using version 2.65 or earlier of the SQL Server ODBC driver. The SERVER keyword is required if DRIVER is specified and DriverCompletion is set to SQL_DRIVER_NOPROMPT. |
| DSN | Name of an existing ODBC user or system data source. |
| Fallback (SQL Server 6.5 only) |
When yes, instructs the driver to attempt connection to a fallback server if connection to a primary server fails. The login time-out (set with ODBC SQLSetConnectAttr, attribute SQL_ATTR_LOGIN_TIMEOUT) must be set for fallback to occur. When no, no attempt at a fallback connection is made. This option applies only to standby servers. It does not apply to a virtual server in a cluster/failover configuration. |
| FILEDSN | Name of an existing ODBC file data source. |
| LANGUAGE | SQL Server language name (optional). SQL Server can store messages for multiple languages in sysmessages. If connecting to a SQL Server with multiple languages, Language specifies which set of messages are used for the connection. |
| Network | Name of a network library dynamic-link library. The name need not include the path and must not include the .dll file name extension, for example, Network=dbnmpntw. |
| PWD | The password for the SQL Server login account specified in the UID parameter. PWD need not be specified if the login has a NULL password or when using Windows Authentication (Trusted_Connection = yes). |
| SAVEFILE | Name of an ODBC data source file into which the attributes of the current connection are saved if the connection is successful. |
| SERVER | Name of a server running SQL Server on the network. The value must be either the name of a server on the network, or the name of a SQL Server Client Network Utility advanced server entry. You can enter (local) as the server name on Microsoft Windows® NT 4.0 to connect to a copy of SQL Server running on the same computer. SQL Server 2000 supports multiple instances of SQL Server running on the same computer. To specify a named instance of SQL Server, the server name is specified as ServerName\InstanceName. For more information about server names, see Managing Clients. |
| QueryLogFile | Full path and file name of a file to use to log data on long-running queries. |
| QueryLog_On | When yes, logging long-running query data is enabled on the connection. When no, long-running query data is not logged. |
| QueryLogTime | Digit character string specifying the threshold (in milliseconds) for logging long-running queries. Any query that does not get a response in the time specified is written to the long-running query log file. |
| QuotedID | When yes, QUOTED_IDENTIFIERS is set ON for the connection, SQL Server uses the SQL-92 rules regarding the use of quotation marks in SQL statements. When no, QUOTED_IDENTIFIERS is set OFF for the connection. SQL Server then follows the legacy Transact-SQL rules regarding the use of quotation marks in SQL statements. For more information, see Effects of SQL-92 Options. |
| Regional | When yes, the SQL Server ODBC driver uses client settings when converting currency, date, and time data to character data. The conversion is one way only; the driver does not recognize non-ODBC standard formats for date strings or currency values within; for example, a parameter used in an INSERT or UPDATE statement. When no, the driver uses ODBC standard strings to represent currency, date, and time data that is converted to string data. |
| StatsLogFile | Full path and file name of a file used to record SQL Server ODBC driver performance statistics. |
| StatsLog_On | When yes, enables the capture of SQL Server ODBC driver performance data. When no, SQL Server ODBC driver performance data is not available on the connection. |
| Trusted_Connection | When yes, instructs the SQL Server ODBC driver to use Windows Authentication Mode for login validation. The UID and PWD keywords are optional. When no, instructs the SQL Server ODBC driver to use a SQL Server username and password for login validation. The UID and PWD keywords must be specified. |
| UID | A valid SQL Server login account. UID need not be specified when using Windows Authentication. |
| UseProcForPrepare (SQL Server 6.5 and earlier only) |
When 1, instructs the SQL Server ODBC driver to create temporary stored procedures when statements are prepared with SQLPrepare. The temporary stored procedures are not dropped until the connection is broken.
When 2, the SQL Server ODBC driver creates temporary stored procedures for SQLPrepare, but only one procedure is created per statement handle and the procedure is dropped when the statement handle becomes invalid or a new SQL statement is prepared. When 0, the SQL Server ODBC driver does not create temporary stored procedures for SQLPrepare. |
| WSID | Workstation ID. Typically, this is the network name of the computer on which the application resides (optional). If specified, this value is stored in the master.dbo.sysprocesses column hostname and is returned by sp_who and the Transact-SQL HOST_NAME function. |
Note Regional conversion settings apply to currency, numeric, date, and time data types. The conversion setting is only applicable to output conversion and is only visible when currency, numeric, date, or time values are converted to character strings.
The driver uses the locale registry settings for the current user. The driver does not honor the current thread's locale if the application sets it after connection by, for example, calling SetThreadLocale.
Altering the regional behavior of a data source can cause application failure. An application that parses date strings, and expects date strings to appear as defined by ODBC, could be adversely affected by altering this value.
The SQL Server ODBC driver defines connection attributes that either replace or enhance connection-string keywords. Several connection-string keywords have default values specified by the SQL Server ODBC driver. For more information about SQL Server connection attributes and driver default behaviors, see SQLSetConnectAttr.
When the SQLDriverConnect DriverCompletion parameter value is SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, or SQL_DRIVER_COMPLETE_REQUIRED, the SQL Server ODBC driver retrieves keyword values from the displayed dialog box. If the keyword value is passed in the connection string and the user does not alter the value for the keyword in the dialog box, the SQL Server ODBC driver uses the value from the connection string. If the value is not set in the connection string and the user makes no assignment in the dialog box, the driver uses the default.
SQLDriverConnect must be given a valid WindowHandle when any DriverCompletion value requires (or could require) the display of the driver's connection dialog box. An invalid handle returns SQL_ERROR.
Specify either the DRIVER or DSN keywords. ODBC states that a driver uses the leftmost of these two keywords and ignores the other if both are specified. If DRIVER is specified, or is the leftmost of the two, and the SQLDriverConnect DriverCompletion parameter value is SQL_DRIVER_NOPROMPT, the SERVER keyword and an appropriate value are required.
When SQL_DRIVER_NOPROMPT is specified, user authentication keywords must be present with values. The driver ensures that either the string "Trusted_Connection=yes" or both the UID and PWD keywords are present.
If the DriverCompletion parameter value is SQL_DRIVER_NOPROMPT or SQL_DRIVER_COMPLETE_REQUIRED and the language or database comes from the connection string and either is invalid, SQLDriverConnect returns SQL_ERROR.
If the DriverCompletion parameter value is SQL_DRIVER_NOPROMPT or SQL_DRIVER_COMPLETE_REQUIRED and the language or database comes from the ODBC data source definitions and either is invalid, SQLDriverConnect uses the default language or database for the specified user ID and returns SQL_SUCCESS_WITH_INFO.
If the DriverCompletion parameter value is SQL_DRIVER_COMPLETE or SQL_DRIVER_PROMPT and if the language or database is invalid, SQLDriverConnect redisplays the dialog box.
Examples
The following call illustrates the least amount of data required for SQLDriverConnect:
SQLDriverConnect(hdbc, hwnd,
(SQLTCHAR*) "DRIVER={SQL Server};" SQL_NTS, szOutConn,
MAX_CONN_OUT, cbOutConn, SQL_DRIVER_COMPLETE);
The following connection strings illustrate minimum required data when the DriverCompletion parameter value is SQL_DRIVER_NOPROMPT:
"DSN=Human Resources;UID=Smith;PWD=Sesame"
"DSN=Human Resources;Trusted_Connection=yes"
"FILEDSN=HR_FDSN;UID=Smith;PWD=Sesame"
"FILEDSN=HR_FDSN;Trusted_Connection=yes"
"DRIVER={SQL Server};SERVER=hrserver;UID=Smith;PWD=Sesame"
"DRIVER={SQL Server};SERVER=hrserver;Trusted_Connection=yes"