Contents|Index|Previous|Next
SQLDriverConnect
Conformance
Version Introduced: ODBC 1.0
Standards Compliance: ODBC
Summary
SQLDriverConnect is an alternative to SQLConnect. It supports data sources that require more connection information than the
three arguments in SQLConnect, dialog boxes to prompt the user for all connection information, and data
sources that are not defined in the system information.
SQLDriverConnect provides the following connection attributes:
Establish a connection using a connection string that contains the data source
name, one or more user IDs, one or more passwords, and other information
required by the data source.
Establish a connection using a partial connection string or no additional
information; in this case, the Driver Manager and the driver can each prompt the
user for connection information.
Establish a connection to a data source that is not defined in the system
information. If the application supplies a partial connection string, the driver
can prompt the user for connection information.
Establish a connection to a data source using a connection string constructed
from the information in a .DSN file.
After a connection is established, SQLDriverConnect returns the completed connection string. The application can use this string
for subsequent connection requests. For more information, see “Connecting with SQLDriverConnect” in Chapter 6, “Connecting to a Data Source or Driver.”
Syntax
SQLRETURN SQLDriverConnect(
SQLHDBC ConnectionHandle,
SQLHWND WindowHandle,
SQLCHAR * InConnectionString,
SQLSMALLINT StringLength1,
SQLCHAR * OutConnectionString,
SQLSMALLINT BufferLength,
SQLSMALLINT * StringLength2Ptr,
SQLUSMALLINT DriverCompletion);
Arguments
ConnectionHandle [Input]
Connection handle.
WindowHandle [Input]
Window handle. The application can pass the handle of the parent window, if
applicable, or a null pointer if either the window handle is not applicable or if SQLDriverConnect will not present any dialog boxes.
InConnectionString [Input]
A full connection string (see the syntax in “Comments”), a partial connection
string, or an empty string.
StringLength1 [Input]
Length of *InConnectionString, in bytes.
OutConnectionString [Output]
Pointer to a buffer for the completed connection string. Upon successful
connection to the target data source, this buffer contains the completed connection
string. Applications should allocate at least 1024 bytes for this buffer.
BufferLength [Input]
Length of the *OutConnectionString buffer.
StringLength2Ptr [Output]
Pointer to a buffer in which to return the total number of bytes (excluding
the null-termination byte) available to return in *OutConnectionString. If the number of bytes available to return is greater than or equal to BufferLength, the completed connection string in *OutConnectionString is truncated to BufferLength minus the length of a null-termination character.
DriverCompletion [Input]
Flag that indicates whether the Driver Manager or driver must prompt for more
connection information:
SQL_DRIVER_PROMPT,
SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED, or SQL_DRIVER_NOPROMPT.
(See “Comments,” for additional information.)
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, or
SQL_INVALID_HANDLE.
Diagnostics
When SQLDriverConnect returns either SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE
value may be obtained by calling SQLGetDiagRec with an fHandleType of SQL_HANDLE_DBC and an hHandle of ConnectionHandle. The following table lists the SQLSTATE values commonly returned by SQLDriverConnect and explains each one in the context of this function; the notation “(DM)”
precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return
code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.
SQLSTATE
| Error
| Description
|
01000
| General warning
| Driver-specific informational message. (Function returns
SQL_SUCCESS_WITH_INFO.)
|
01004
| String data, right truncated
| The buffer *OutConnectionString was not large enough to return the entire connection string, so the
connection string was truncated. The length of the untruncated connection string is
returned in *StringLength2Ptr. (Function returns SQL_SUCCESS_WITH_INFO.)
|
01S00
| Invalid connection string attribute
| An invalid attribute keyword was specified in the connection string (InConnectionString), but the driver was able to connect to the data source anyway. (Function
returns SQL_SUCCESS_WITH_INFO.)
|
01S02
| Option value changed
| The driver did not support the specified value pointed to by the ValuePtr argument in SQLSetConnectAttr and substituted a similar value. (Function returns SQL_SUCCESS_WITH_INFO.)
|
01S08
| Error saving file DSN
| The string in *InConnectionString contained a FILEDSN keyword, but the .DSN file was not saved. (Function returns
SQL_SUCCESS_WITH_INFO.)
|
01S09
| Invalid keyword
| (DM) The string in *InConnectionString contained a SAVEFILE keyword, but not a DRIVER or a FILEDSN keyword. (Function returns SQL_SUCCESS_WITH_INFO.)
|
08001
| Client unable to establish connection
| The driver was unable to establish a connection with the data source.
|
08002
| Connection name in use
| (DM) The specified ConnectionHandle had already been used to establish a connection with a data source and the
connection was still open.
|
08004
| Server rejected the connection
| The data source rejected the establishment of the connection for
implementation-defined reasons.
|
08S01
| Communication link failure
| The communication link between the driver and the data source to which the
driver was attempting to connect failed before the function completed processing.
|
28000
| Invalid authorization specification
| Either the user identifier or the authorization string or both as specified in
the connection string (InConnectionString) violated restrictions defined by the data source.
|
HY000
| General error
| An error occurred for which there was no specific SQLSTATE and for which no
implementation-specific SQLSTATE was defined. The error message returned by SQLGetDiagRec in the *szMessageText buffer describes the error and its cause.
|
HY001
| Memory allocation error
| The Driver Manager was unable to allocate memory required to support execution
or completion of the function.
The driver was unable to allocate memory required to support execution or
completion of the function.
|
HY013
| Memory management error
| The function call could not be processed because the underlying memory objects
could not be accessed, possibly because of low memory conditions.
|
HY090
| Invalid string or buffer length
| (DM) The value specified for argument StringLength1 was less than 0 and was not equal to SQL_NTS.
(DM) The value specified for argument BufferLength was less than 0.
|
HY092
| Invalid attribute/option identifier
| (DM) The DriverCompletion argument was SQL_DRIVER_PROMPT, and the WindowHandle argument was a null pointer.
|
HY110
| Invalid driver completion
| (DM) The value specified for the argument DriverCompletion was not equal to SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE,
SQL_DRIVER_COMPLETE_REQUIRED, or SQL_DRIVER_NOPROMPT.
(DM) Connection pooling was enabled, and the value specified for the argument DriverCompletion was not equal to SQL_DRIVER_NOPROMPT.
|
HYC00
| Optional feature not implemented
| The driver does not support the version of ODBC behavior that the application
requested.
|
HYT00
| Timeout expired
| The login timeout period expired before the connection to the data source
completed. The timeout period is set through SQLSetConnectAttr, SQL_ATTR_LOGIN_TIMEOUT.
|
HYT01
| Connection timeout expired
| The connection timeout period expired before the data source responded to the
request. The connection timeout period is set through SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
|
IM001
| Driver does not support this function
| (DM) The driver corresponding to the specified data source name does not
support the function.
|
IM002
| Data source not found and no default driver specified
| (DM) The data source name specified in the connection string (InConnectionString) was not found in the system information and there was no default driver
specification.
(DM) ODBC data source and default driver information could not be found in the
system information.
|
IM003
| Specified driver could not be loaded
| (DM) The driver listed in the data source specification in the system
information, or specified by the DRIVER keyword, was not found or could not be loaded for some other reason.
|
IM004
| Driver’s SQLAllocHandle on SQL_HANDLE_
ENV failed
| (DM) During SQLDriverConnect, the Driver Manager called the driver’s SQLAllocHandle function with an fHandleType of SQL_HANDLE_ENV and the driver returned an error.
|
IM005
| Driver’s SQLAllocHandle on SQL_HANDLE_
DBC failed.
| (DM) During SQLDriverConnect, the Driver Manager called the driver’s SQLAllocHandle function with an fHandleType of SQL_HANDLE_DBC and the driver returned an error.
|
IM006
| Driver’s SQLSetConnectAttr failed
| (DM) During SQLDriverConnect, the Driver Manager called the driver’s SQLSetConnectAttr function and the driver returned an error.
|
IM007
| No data source or driver specified; dialog prohibited
| No data source name or driver was specified in the connection string and DriverCompletion was SQL_DRIVER_NOPROMPT.
|
IM008
| Dialog failed
| The driver attempted to display its login dialog box and failed.
WindowHandle was a null pointer, and DriverCompletion was not SQL_DRIVER_NO_PROMPT.
|
IM009
| Unable to load translation DLL
| The driver was unable to load the translation DLL that was specified for the
data source or for the connection.
|
IM010
| Data source name too long
| (DM) The attribute value for the DSN keyword was longer than
SQL_MAX_DSN_LENGTH characters.
|
IM011
| Driver name too long
| (DM) The attribute value for the DRIVER keyword was longer than 255 characters.
|
IM012
| DRIVER keyword syntax error
| (DM) The keyword-value pair for the DRIVER keyword contained a syntax error.
(DM) The string in *InConnectionString contained a FILEDSN keyword, but the .DSN file did not contain a DRIVER keyword or a DSN keyword.
|
IM014
| Invalid name of file DSN
| (DM) The string in *InConnectionString contained a FILEDSN keyword, but the name of the .DSN file was invalid.
|
IM015
| Corrupt file data source
| (DM) The string in *InConnectionString contained a FILEDSN keyword, but the .DSN file was unreadable.
|
Comments
Connection Strings
A connection string has the following syntax:
connection-string ::= empty-string[;] | attribute[;] | attribute; connection-string
empty-string ::=
attribute ::= attribute-keyword=attribute-value | DRIVER=[{]attribute-value[}]
attribute-keyword ::= DSN | UID | PWD
| driver-defined-attribute-keyword
attribute-value ::= character-string
driver-defined-attribute-keyword ::= identifier
where character-string has zero or more characters; identifier has one or more characters; attribute-keyword is not case-sensitive; attribute-value may be case-sensitive; and the value of the DSN keyword does not consist solely of blanks. Because of connection string and
initialization file grammar, keywords and attribute values that contain the
characters []{}(),;?*=!@ should be avoided. The value of the DSN keyword cannot consist only of blanks, and should not contain leading blanks.
Because of the grammar of the system information, keywords and data source
names cannot contain the backslash (\) character. Applications do not have to add
braces around the attribute value after the DRIVER keyword unless the attribute
contains a semicolon (“;”), in which case the braces are required. If the
attribute value that the driver receives includes braces, the driver should not
remove them, but they should be part of the returned connection string.
Keyword-Value Pairs
The connection string may include any number of driver-defined keywords.
Because the DRIVER keyword does not use information from the system information, the driver must
define enough keywords so that a driver can connect to a data source using
only the information in the connection string. (For more information, see “Driver
Guidelines,” later in this section.) The driver defines which keywords are
required to connect to the data source.
The following table describes the attribute values of the DSN, FILEDSN, DRIVER, UID, PWD, and SAVEFILE keywords.
Keyword
| Attribute value description
|
DSN
| Name of a data source as returned by SQLDataSources or the data sources dialog box of SQLDriverConnect.
|
FILEDSN
| Name of a .DSN file from which a connection string will be built for the data
source. These data sources are called file data sources.
|
DRIVER
| Description of the driver as returned by the SQLDrivers function. For example, Rdb or SQL Server.
|
UID
| A user ID.
|
PWD
| The password corresponding to the user ID, or an empty string if there is no
password for the user ID (PWD=;).
|
SAVEFILE
| The file name of a .DSN file in which the attribute values of keywords used in
making the present, successful connection should be saved.
|
For information about how an application chooses a data source or driver, see “Choosing a Data Source or Driver” in Chapter 6, “Connecting to a Data Source or Driver.”
If any keywords are repeated in the connection string, the driver uses the
value associated with the first occurrence of the keyword. If the DSN and DRIVER keywords are included in the same connection string, the Driver Manager and
the driver use whichever keyword appears first.
The FILEDSN and DSN keywords are mutually exclusive: whichever keyword appears first is used, and
the one that appears second is ignored. The FILEDSN and DRIVER keywords, on the other hand, are not mutually exclusive. If any keyword
appears in a connection string with FILEDSN, then the attribute value of the keyword in the connection string is used
rather than the attribute value of the same keyword in the .DSN file.
If the FILEDSN keyword is used, the keywords specified in a .DSN file are used to create a
connection string. (For more information, see “File Data Sources” later in this
section.) The UID keyword is optional; a .DSN file may be created with only the DRIVER keyword. The PWD keyword is not stored in a .DSN file. The default directory for saving and
loading a .DSN file will be a combination of the path specified by CommonFileDir
in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion and
ODBC\DataSources”. (If CommonFileDir were “C:\Program Files\Common Files”, the default
directory would be “C:\Program Files\Common Files\ODBC\Data Sources”.)
Note A .DSN file can be manipulated directly by calling the SQLReadFileDSN and SQLWriteFileDSN functions in the installer DLL.
If the SAVEFILE keyword is used, the attribute values of keywords used in making the present,
successful connection will be saved as a .DSN file with the name of the
attribute value of the SAVEFILE keyword. The SAVEFILE keyword must be used in conjunction with the DRIVER keyword, the FILEDSN keyword, or both, or the function returns SQL_SUCCESS_WITH_INFO with SQLSTATE
01S09 (Invalid keyword). The SAVEFILE keyword must appear before the DRIVER keyword in the connection string, or the results will be undefined.
Driver Manager Guidelines
The Driver Manager constructs a connection string to pass to the driver in the InConnectionString argument of the driver’s SQLDriverConnect function. Note that the Driver Manager does not modify the InConnectionString argument passed to it by the application.
The action of the Driver Manager is based on the value of the DriverCompletion argument:
SQL_DRIVER_PROMPT: If the connection string does not contain either the DRIVER, DSN, or FILEDSN keyword, the Driver Manager displays the Data Sources dialog box. It
constructs a connection string from the data source name returned by the dialog box and
any other keywords passed to it by the application. If the data source name
returned by the dialog box is empty, the Driver Manager specifies the
keyword-value pair DSN=Default. (This dialog box will not display a data source with the
name “Default”.)
SQL_DRIVER_COMPLETE or SQL_DRIVER_COMPLETE_REQUIRED: If the connection string
specified by the application includes the DSN keyword, the Driver Manager copies the connection string specified by the
application. Otherwise, it takes the same actions as it does when DriverCompletion is SQL_DRIVER_PROMPT.
SQL_DRIVER_NOPROMPT: The Driver Manager copies the connection string specified
by the application.
If the connection string specified by the application contains the DRIVER keyword, the Driver Manager copies the connection string specified by the
application.
Using the connection string it has constructed, the Driver Manager determines
which driver to use, loads that driver, and passes the connection string it has
constructed to the driver; for more information about the interaction of the
Driver Manager and the driver, see the “Comments” section in SQLConnect. If the connection string does not contain the DRIVER keyword, the Driver Manager determines which driver to use as follows:
1 If the connection string contains the DSN keyword, the Driver Manager retrieves the driver associated with the data
source from the system information.
2 If the connection string does not contain the DSN keyword or the data source is not found, the Driver Manager retrieves the
driver associated with the Default data source from the system information. (For
more information, see “Default Subkey” in Chapter 19, “Configuring Data Sources.”) The Driver Manager changes the
value of the DSN keyword in the connection string to “DEFAULT.”
3 If the DSN keyword in the connection string is set to “DEFAULT,” the Driver Manager
retrieves the driver associated with the Default data source from the system
information.
4 If the data source is not found and the Default data source is not found, the
Driver Manager returns SQL_ERROR with SQLSTATE IM002 (Data source not found and
no default driver specified).
File Data Sources
If the connection string specified by the application in the call to SQLDriverConnect contains the FILEDSN keyword, and this keyword is not superseded by either the DSN or DRIVER keyword, then the Driver Manager creates a connection string using the
information in the .DSN file and the InConnectionString argument. The Driver Manager proceeds as follows:
1 Checks whether the file name of the .DSN file is valid. If not, it returns
SQL_ERROR with SQLSTATE IM014 (Invalid name of file DSN). If the file name is an
empty string (“”), and SQL_DRIVER_NOPROMPT is not specified, then the File-Open
dialog box is displayed. If the file name contains a valid path but no file
name or an invalid file name, and SQL_DRIVER_NOPROMPT is not specified, then the
File-Open dialog box is displayed with the current directory set to the one
specified in the file name. If the file name is an empty string (“”) or the file
name contains a valid path but no file name or an invalid file name, and
SQL_DRIVER_NOPROMPT is specified, then SQL_ERROR is returned with SQLSTATE IM014
(Invalid name of file DSN).
2 Reads all of the keywords in the [ODBC] section of the .DSN file. If the
DRIVER keyword is not present, it returns SQL_ERROR with SQLSTATE IM012 (Driver
keyword syntax error), except where the .DSN file is unshareable, and so contains
only the DSN keyword.
If the file data source is unshareable, the Driver Manager reads the value of
the DSN keyword, and connects as necessary to the user or system data source pointed
to by the unshareable file data source. Steps 3 through 5 are not performed.
3 Constructs a connection string for the driver. The driver connection string is
the union of the keywords specified in the .DSN file and those specified in
the original application connection string. Rules for the construction of the
driver connection string where keywords overlap are as follows:
If the DRIVER keyword exists in the application connection string, and the drivers
specified by the DRIVER keywords are not the same in the .DSN file and the application connection
string, then the driver information in the .DSN file is ignored and the driver
information in the application connection string is used. If the drivers specified
by the DRIVER keyword are the same in the .DSN file and the application’s connection
string, then where all keywords overlap, those specified in the application
connection string have precedence over those specified in the .DSN file.
In the new connection string, the FILEDSN keyword is eliminated.
4 Loads the driver by looking in the registry entry
HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\<Driver Name>\Driver where <Driver Name> is specified by the DRIVER keyword.
5 Passes the driver the new connections string.
For examples of .DSN files, see “Connecting Using File Data Sources” in Chapter 6, “Connecting to a Data Source or Driver.”
SAVEFILE Keyword
If the connection string specified by the application contains the SAVEFILE keyword, then the Driver Manager saves the connection string in a .DSN file.
The Driver Manager proceeds as follows:
1 Checks whether the file name of the .DSN file included as the attribute value
of the SAVEFILE keyword is valid. If not, it returns SQL_ERROR with SQLSTATE IM014 (Invalid
name of file DSN). The validity of the file name is determined by standard
system naming rules. If the file name is an empty string (“”), and the DriverCompletion argument is not SQL_DRIVER_NOPROMPT, then the file name is valid. If the file
name already exists, then if DriverCompletion is SQL_DRIVER_NOPROMPT, the file is overwritten. If DriverCompletion is SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, or SQL_DRIVER_COMPLETE_REQUIRED, a
dialog box is displayed prompting the user to specify whether the file should
be overwritten. If No is entered, then the File-Save dialog box is displayed.
2 If the driver returns SQL_SUCCESS, and the file name was not an empty string,
then the Driver Manager writes the connection information returned in the OutConnectionString argument to the specified file with the format specified in the “Connection
Strings” section earlier in this chapter.
3 If the driver returns SQL_SUCCESS, and the file name was an empty string (“”),
then the Driver Manager calls the File-Save common dialog box with the hwnd specified, and writes the connection information returned in OutConnectionString to the file specified in the File-Save common dialog box with the format
specified in the “Connection Strings” section earlier in this chapter.
4 If the driver returns SQL_SUCCESS, it returns the OutConnectionString argument containing the connection string to the application.
5 If the driver returns SQL_SUCCESS_WITH_INFO or SQL_ERROR, then the Driver
Manager returns the SQLSTATE to the application.
Driver Guidelines
The driver checks whether the connection string passed to it by the Driver
Manager contains the DSN or DRIVER keyword. If the connection string contains the DRIVER keyword, the driver cannot retrieve information about the data source from
the system information. If the connection string contains the DSN keyword or does not contain either the DSN or the DRIVER keyword, the driver can retrieve information about the data source from the
system information as follows:
1 If the connection string contains the DSN keyword, the driver retrieves the information for the specified data source.
2 If the connection string does not contain the DSN keyword, the specified data source is not found, or the DSN keyword is set to “DEFAULT,” the driver retrieves the information for the
Default data source.
The driver uses any information it retrieves from the system information to
augment the information passed to it in the connection string. If the information
in the system information duplicates information in the connection string, the
driver uses the information in the connection string.
Based on the value of DriverCompletion, the driver prompts the user for connection information, such as the user ID
and password, and connects to the data source:
SQL_DRIVER_PROMPT: The driver displays a dialog box, using the values from the
connection string and system information (if any) as initial values. When the
user exits the dialog box, the driver connects to the data source. It also
constructs a connection string from the value of the DSN or DRIVER keyword in *InConnectionString and the information returned from the dialog box. It places this connection
string in the *OutConnectionString buffer.
SQL_DRIVER_COMPLETE or SQL_DRIVER_COMPLETE_REQUIRED: If the connection string
contains enough information, and that information is correct, the driver
connects to the data source and copies *InConnectionString to *OutConnectionString. If any information is missing or incorrect, the driver takes the same
actions as it does when DriverCompletion is SQL_DRIVER_PROMPT, except that if DriverCompletion is SQL_DRIVER_COMPLETE_REQUIRED, the driver disables the controls for any
information not required to connect to the data source.
SQL_DRIVER_NOPROMPT: If the connection string contains enough information, the
driver connects to the data source and copies *InConnectionString to *OutConnectionString. Otherwise, the driver returns SQL_ERROR for SQLDriverConnect.
On successful connection to the data source, the driver also sets *StringLength2Ptr to the length of the output connection string that is available to return in *OutConnectionString.
If the user cancels a dialog box presented by the Driver Manager or the
driver, SQLDriverConnect returns SQL_NO_DATA.
For information about how the Driver Manager and the driver interact during
the connection process, see SQLConnect.
If a driver supports SQLDriverConnect, the driver keyword section of the system information for the driver must
contain the ConnectFunctions keyword with the second character set to “Y”.
Connecting when Connection Pooling is Enabled
Connection pooling allows an application to reuse a connection that has
already been created. When SQLDriverConnect is called, the Driver Manager attempts to make the connection using a
connection that is part of a pool of connections in an environment that has been
designated for connection pooling. For more information on connection pooling, see SQLConnect.
The following restrictions apply when an application calls SQLDriverConnect to connect to a pooled connection:
No connection pooling processing is performed when the SAVEFILE keyword is specified in the connection string.
If connection pooling is enabled, SQLDriverConnect can only be called with a DriverCompletion argument of SQL_DRIVER_NOPROMPT; if SQLDriverConnect is called with any other DriverCompletion, SQLSTATE HY110 (Invalid driver completion) will be returned.
Connection Attributes
The SQL_ATTR_LOGIN_TIMEOUT connection attribute, set using SQLSetConnectAttr, defines the number of seconds to wait for a login request to complete with a
successful connection by the driver before returning to the application. If
the user is prompted to complete the connection string, a waiting period for each
login request begins when the driver starts the connection process.
The driver opens the connection in SQL_MODE_READ_WRITE access mode by default.
To set the access mode to SQL_MODE_READ_ONLY, the application must call SQLSetConnectAttr with the SQL_ATTR_ACCESS_MODE attribute prior to calling SQLDriverConnect.
If a default translation library is specified in the system information for
the data source, the driver loads it. A different translation library can be
loaded by calling SQLSetConnectAttr with the SQL_ATTR_TRANSLATE_LIB attribute. A translation option can be
specified by calling SQLSetConnectAttr with the SQL_ATTR_TRANSLATE_OPTION option.
Code Example
See the “Connecting with SQLDriverConnect” section of Chapter 6, “Connecting to a Data Source or Driver.”
Related Functions
For information about
| See
|