The SQLDriverConnect() function is an alternative to the SQLConnect() function. You can use the SQLDriverConnect() function when the data source requires more than the three parameters that are supported by the SQLConnect() function (data source name, user ID, and password) or when you require the CLI driver to prompt the user for required connection information.
A complete connection string is returned in plain text only after a connection is successful. You can code your application to store the returned connection string for subsequent connection requests.
SQLRETURN SQLDriverConnect (
SQLHDBC ConnectionHandle, /* hdbc */
SQLHWND WindowHandle, /* hwnd */
SQLCHAR *InConnectionString, /* szConnStrIn */
SQLSMALLINT InConnectionStringLength, /* cbConnStrIn */
SQLCHAR *OutConnectionString, /* szConnStrOut */
SQLSMALLINT OutConnectionStringCapacity, /* cbConnStrOutMax */
SQLSMALLINT *OutConnectionStringLengthPtr, /* pcbConnStrOut */
SQLUSMALLINT DriverCompletion); /* fDriverCompletion */
Data type | Argument | Use | Description |
---|---|---|---|
SQLHDBC | ConnectionHandle | Input | Connection handle. |
SQLHWND | WindowHandle | Input | Window handle. The WindowHandle argument
value is the parent Windows operating
system handle. The window handle is supported only on Windows operating systems. If a NULL value is passed, no user prompt is presented. |
SQLCHAR * | InConnectionString | Input | Connection string. See the usage section for details. |
SQLSMALLINT | InConnectionStringLength | Input | Number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function) that are needed to store the connection string that is specified for the InConnectionString argument. |
SQLSMALLINT * | OutConnectionString | Output | Pointer to a buffer for the completed connection string for
a successful connection or the NULL value. For this buffer, applications must allocate at least the number of bytes that you specify for the predefined maximum length (SQL_MAX_OPTION_STRING_LENGTH). |
SQLSMALLINT | OutConnectionString |
Input | Number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function) that are needed to store the connection string that is returned through the buffer that is specified for the OutConnectionString argument. |
SQLSMALLINT * | OutConnectionString |
Output | Pointer to the number of SQLCHAR elements (or SQLWCHAR elements
for the Unicode variant of this function), excluding the null-termination character,
that is available to return in the buffer that is specified by the OutConnectionString argument.
If the returned length value in the *OutConnectionStringLengthPtr argument is greater than or equal to the OutConnectionStringCapacity argument value, the completed connection string in the buffer that is specified by the OutConnectionString argument is truncated to OutConnectionStringCapacity - 1 SQLCHAR or SQLWCHAR elements. |
SQLUSMALLINT | DriverCompletion | Input | Indicator of when the CLI driver
prompts the user for more information. Possible values are as
follows:
|
>>-"--+---------------------------------+--+-DSN--=--dsn_name--;----------------------+--> '-DRIVER--=--{--driver_name--}--;-' '-DATABASE--=--+-database_name--------+--;-' '-database:server:port-' >--+-------------------------------------------------------------------------+--> '-UID--=--user_id--;--PWD--=--password--;--+----------------------------+-' '-NEWPWD--=--new_password--;-' .-;---------------------------------. V | >----CLI_keyword--=--CLI_keyword_value-+--;--"-----------------><
The OutConnectionString argument can be a pointer to a buffer or the NULL value. If a pointer to a buffer is specified, the buffer is populated with the connection string upon a successful connection. Applications that require multiple connections to the same database for the same user ID can store this output connection string. The returned connection string can then be used as the input connection string value on future calls to the SQLDriverConnect() function. The NULL value causes the pointer that is specified for the OutConnectionString LengthPtr argument to return the number of characters in the connection string upon successful connection.
If any keywords exist in the CLI initialization file, the keywords and their values are used to augment the information that is passed to the CLI driver in the connection string. If the information in the CLI initialization file contradicts information in the connection string, the values in the connection string take precedence.
After a connection is established, the complete connection string is returned. Applications that require multiple connections to the same database with the same user ID can store this output connection string. This string can then be used as the input connection string value on future SQLDriverConnect() calls.
The following table contains the diagnostic messages that the SQLDriverConnect() function can return:
SQLSTATE | Description | Explanation |
---|---|---|
01004 | Data truncated. | The buffer szConnstrOut was not large enough to hold the entire connection string. The *OutConnectionStringLengthPtr argument contains the actual length of the connection string that is available for return. The function returns SQL_SUCCESS_WITH_INFO. |
01S00 | Invalid connection string attribute. | An invalid keyword or attribute value was specified in the
input connection string, but the connection to the data source was
successful because one of the following events occurred:
The function returns SQL_SUCCESS_WITH_INFO. |
HY000 | General error.
Dialog failed |
The information that was specified in the connection string
was insufficient for making a connection request, but the dialog was
prohibited by setting fCompletion to SQL_DRIVER_NOPROMPT.
The attempt to start the dialog failed. |
HY090 | Invalid string or buffer length. | The value specified for the InConnectionStringLength argument
was less than 0 but not equal to SQL_NTS. The value specified for OutConnectionStringCapacity was less than 0. |
HY110 | Invalid driver completion. | The value specified for the fCompletion argument was not equal to one of the valid values. |
rc = SQLDriverConnect(hdbc,
(SQLHWND)sqlHWND,
InConnectionString,
InConnectionStringLength,
OutConnectionString,
OutConnectionStringCapacity,
StrLength2,
DriveCompletion);