MDAC 2.5 SDK - ODBC Programmer's Reference
Chapter 21: ODBC API Reference

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 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 1,024 bytes for this buffer.

BufferLength

[Input]
Length of the *OutConnectionString buffer. If the *OutConnectionString value is a Unicode string (when calling SQLDriverConnectW), the BufferLength argument must be an even number.

StringLength2Ptr

[Output]
Pointer to a buffer in which to return the total number of characters (excluding the null-termination character) available to return in *OutConnectionString. If the number of characters 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.

(For additional information, see "Comments.")

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.

Comments

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 []{}(),;?*=!@ not enclosed with braces 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.

A DSN or connection string value enclosed with braces ({}) containing any of the characters []{}(),;?*=!@ is passed intact to the driver. However, when using these characters in a keyword, the Driver Manager returns an error when working with file DSNs but passes the connection string to the driver for regular connection strings. Avoid using embedded braces in a keyword value.

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.

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. 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, connects to 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 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 thus 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 prompts the user to specify whether the file should be overwritten. If No is entered, then the File-Save dialog box appears.
   
   
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 be called only 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

For a code example, see the "Connecting with SQLDriverConnect" section of Chapter 6, "Connecting to a Data Source or Driver."

Related Functions