SQLDriverConnect

Applies to: SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW)

The SQL Server Native Client 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 Native Client ODBC driver.

For a list of the keywords available in the SQL Server Native Client ODBC driver, see Using Connection String Keywords with SQL Server Native Client.

For more information about SQL Server connection attributes and driver default behaviors, see SQLSetConnectAttr.

For a discussion of connection string keywords that are valid for SQL Server Native Client, see Using Connection String Keywords with SQL Server Native Client.

When the SQLDriverConnectDriverCompletion parameter value is SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, or SQL_DRIVER_COMPLETE_REQUIRED, the SQL Server Native Client 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 Native Client 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 SQLDriverConnectDriverCompletion 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.

SQLDriverConnect Support for High Availability, Disaster Recovery

For more information about using SQLDriverConnect to connect to a Always On availability groups cluster, see SQL Server Native Client Support for High Availability, Disaster Recovery.

SQLDriverConnect Support for Service Principal Names (SPNs)

SQLDDriverConnect will use the ODBC Login dialog box when prompting is enabled. This allows SPNs to be entered for both the principal server and its failover partner.

SQLDriverConnect will accept the new connection string keywords ServerSPN and FailoverPartnerSPN, and will recognize the new connection attributes SQL_COPT_SS_SERVER_SPN and SQL_COPT_SS_FAILOVER_PARTNER_SPN.

When a connection attribute value is specified more than once, a value that is set programmatically takes precedence over the value in a DSN and a value in a connection string. A value in a DSN takes precedence over a value in a connection string.

When a connection is opened, SQL Server Native Client sets SQL_COPT_SS_MUTUALLY_AUTHENTICATED and SQL_COPT_SS_INTEGRATED_AUTHENTICATION_METHOD to the authentication method used to open the connection.

For more information about SPNs, see Service Principal Names (SPNs) in Client Connections (ODBC).

Examples

The following call illustrates the least amount of data required for SQLDriverConnect:

SQLDriverConnect(hdbc, hwnd,  
    (SQLTCHAR*) TEXT("DRIVER={SQL Server Native Client 10};"), 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;Trusted_Connection=yes"  
  
"FILEDSN=HR_FDSN;Trusted_Connection=yes"  
  
"DRIVER={SQL Server Native Client 10};SERVER=(local);Trusted_Connection=yes"  

See Also

SQLDriverConnect Function
ODBC API Implementation Details
SET ANSI_NULLS (Transact-SQL)
SET ANSI_PADDING (Transact-SQL)
SET ANSI_WARNINGS (Transact-SQL)