SQLDriverConnect function (CLI) - Connect to a data source
Specification:
- CLI 2.1
- ODBC 1.0
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.
Syntax
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 */
Function arguments
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
Capacity |
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
LengthPtr |
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:
|
Usage
InConnectionString argument
- DRIVER=driver_name
- Name of the database driver. You can obtain the name of the database driver with the SQLDrivers() function.
- DSN=dsn_name
- The name of the data source that you are connecting to. The DSN keyword value is required for a connection unless the DriverCompletion argument is equal to SQL_DRIVER_NOPROMPT or the DATABASE keyword value is specified.
- DATABASE=database_name
- The database identifier. The database name can consist of just the database name or can consist of the database name, server name, and port number. If you do not provide a server name and port number, the default values are used. The default server name is LOCALHOST and the default port number is 50000. The DATABASE keyword value is required for a connection unless the DriverCompletion argument is equal to SQL_DRIVER_NOPROMPT or the DSN keyword value is specified.
- UID
- A user ID that is specified for the connection authentication request.
- PWD
- The password that corresponds to the specified user ID.
- NEWPWD
- A new password that is used as part of a change password request.
You can specify a new password in the connection string, or specify
NEWPWD=;
in the connection string for a new password prompt if you do not set the DriverCompletion argument to SQL_DRIVER_NOPROMPT. - CLI_keyword
- A CLI configuration keyword that is used to configure the behavior of the CLI driver. If any CLI keywords are specified more than once in the connection string, the first occurrence of the keyword is used.
- Opening bracket ([)
- Closing bracket (])
- Opening brace ({)
- Closing brace (})
- Comma (,)
- Semicolon (;)
- Question mark (?)
- Asterisk (*)
- Equal sign (=)
- Exclamation mark (!)
- At sign (@)
- Backslash (\)
OutConnectionString argument
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.
DriverCompletion argument
- SQL_DRIVER_COMPLETE
- A dialog is initiated only if there is insufficient information in the connection string. The information from the connection string is used as initial values and is supplemented by data that is entered when the user is prompted.
- SQL_DRIVER_COMPLETE_REQUIRED
- A dialog is initiated only if there is insufficient information in the connection string. The information from the connection string is used as initial values. The user is prompted for required information only.
- SQL_DRIVER_NOPROMPT
- The user is not prompted for any information. A connection is attempted with the information in the connection string. If there is not enough information, the SQL_ERROR message is returned.
- SQL_DRIVER_PROMPT
- A dialog is always initiated. The information from the connection string and the CLI initialization file is used as initial values.
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.
Return codes
- SQL_ERROR
- SQL_INVALID_HANDLE
- SQL_NO_DATA_FOUND
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
Diagnostics
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. |
Example
rc = SQLDriverConnect(hdbc,
(SQLHWND)sqlHWND,
InConnectionString,
InConnectionStringLength,
OutConnectionString,
OutConnectionStringCapacity,
StrLength2,
DriveCompletion);