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 ODBC.INI file or registry.

SQLDriverConnect provides the following connection options:

• 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 ODBC.INI file or registry. If the application supplies a partial connection string, the driver can prompt the user for connection information.

Once a connection is established, SQLDriverConnect returns the completed connection string. The application can use this string for subsequent connection requests.

When SQLDriverConnect returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may be obtained by calling SQLError. 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.

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}
(The braces({}) are literal; the application must specify them.)
attribute-keyword ::= DSN|UID|PWD| driver-defined-attribute-keyword
attribute-value ::= character-string
driver-defined-attribute-keyword ::= identifier

Note The DRIVER keyword was introduced in ODBC 2.0 and is not supported by ODBC 1.0 drivers.

The connection string may include any number of driver-defined keywords. Because the DRIVER keyword does not use information from the ODBC.INI file or registry, 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 in order to connect to the data source.

If any keywords are repeated in the connection string, the driver uses the value associated with the first occurance 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 following table describes the attribute values of the DSN, DRIVER, UID and PWD keywords.

The Driver Manager constructs a connection string to pass to the driver in the szConnStrIn argument of the driver's SQLDriverConnect function. Note that the Driver Manager does not modify the szConnStrIn argument passed to it by the application.

If the connection string specified by the application contains the DSN keyword or does not contain either the DSN or DRIVER keywords, the action of the Driver Manager is based on the value of the fDriverCompletion argument:

• SQL_DRIVER_PROMPT: 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 bxo is empty, the Driver Manager specifies the keyword-value pair DSN=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 fDriverCompletion 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 contains the DSN keyword or does not contain either the DSN or 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 ODBC.INI file or registry.
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 ODBC.INI file or registry. However, the Driver Manager does not change the valuye of the DSN keyword in the connection string.
3. 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).

The driver checks if 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 ODBC>INI file or registry. 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 ODBC.INI file or registry 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 or the specified data source is not found, the driver retrieves the information for the Default data source.

The driver uses any information it retrieves from the ODBC.INI file or registry to augment the information passed to it in the connection string. If the information in the ODBC>INI file or registry duplicates information in the connection string, the driver uses the information in the connection string.

Based on the value of fDriverCompletion, 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 ODBC.INI file or registry (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 szConnStrIn and the information returned from the dialog box. It places this connection string in the buffer referenced by szConnStrOut.
• 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 szConnStrIn to szConnStrOut. If any additional informaiton is missing or incorrect, the driver takes the same actions as it does when fDriverCompletion is SQL_DRIVER_PROMPT, except that if fDriverCompletion is SQL_DRIVER_COMPLETE_REQUIRED, the driver disables the controls for any information not reuqired 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 szConnStrIn to szConnStrOut. Otherwise, the driver returns SQL_ERROR for SQLDriverConnect.

On successful connection to the data source, the driver alo sets pcbConnStrOut to the length of szConnStrOut.

If the user cancels a dialog box presented by the Driver Manager or the driver, SQLDriverConnect returns SQL_NO_DATA_FOUND.

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 ODBC.INF file for the driver must contain the ConnectFunctions keyword with the second character set to "Y".

The SQL_LOGIN_TIMEOUT connection option, set using SQLSetConnectOption, defines the number of seconds to wait for a login request to complete before returning to the application. If the user is prompted to complete the connection string, a waiting period for each login request begins after the user has dismissed each dialog box.

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 SQLSetConnectOption with the SQL_ACCESS_MODE option prior to calling SQLDriverConnect.

If a default translation DLL is specified in the ODBC.INI file or registry for the data source, the driver loads it. A different transaltion DLL can be loaded by calling SQLSetConnectOption with the SQL_TRANSLATE_DLL option. A translation option can be specified by calling SQLSetConnectOption with the SQL_TRANSLATE_OPTION option.

ODBC Router

ODBC Router transparently makes all ODBC drivers on a central Windows Server useable by your network's iPhone/iPod, iPad, Linux, Mac and Windows systems. Years in the making here in the USA, ODBC Router has saved its customers millions of dollars in DLL installations and support costs for less than the price of a new PC and a few minutes installation time. ODBC Router provides a low cost, turnkey database network with enterprise class IT support.

Ditching the ODBC Administrator Control Panel:

By linking your application with the free ODBC Router client-side SDK instead of the ODBC Driver Manager, the need for your end-users to deal with driver installation or an ODBC Control Panel is gone! We even provide a setup function your code may call to display a "network browser" that enables your customer to "find" their ODBC Router server on the network, then "choose" the exact database they want to work with and finally return to your application with a fully-formed ODBC connection-string that may be stored and passed back to SQLConnect or SQLDriverConnect anytime your user wants to initiate a connection that data source. No more walking your customers through the process of adding data sources to ODBC Control Panel or, in the case of non-Windows computers, no need to worry about whether or not a compatible third-party ODBC Driver Manager has been installed for use with your code. (Remember that ODBC Router supports iPhone/iPod, iPad, Mac OS 9, Mac OS X, Linux and Windows.) If there ever are any client-side ODBC support issues, AugSoft can handle them directly with the customer freeing you to focus on the application.

JDBC?

JDBC-in-ODBC drivers (like some 'actual' ODBC drivers, lol) launch a CPU-intensive virtual machine in the background on your machine, which is bad for battery powered laptops, high-volume web servers or entry level desktops (that typically have slow busses and drives). As the world shifted to laptops and shared servers, the whole "virtual machine" concept became a support nightmare and so these days good Java apps are compiled to run as native (not emulated) code. Java developers may use the operating system's native ODBC support from within the JDBC class library using the sun.jdbc.odbc.JdbcOdbcDriver driver with a URL as shown below.

jdbc:odbc:dsn[;key=value]*

Example:

jdbc:odbc:finance;UID=cfo;

IT techs may then complete the database connection on the Customer's machine using ODBC Router or the database vendor's official ODBC driver.

NOTE: By creating ODBC data sources with ODBC Router, your apps will enjoy native speed and database independent connections from either Java/C/C++/C#/ObjC or PHP/PERL/Python/Ruby/BASIC on Linux, Macintosh and Windows. Also be aware that using ODBC Router with the Mac platform is an especially good idea because database vendors have not kept their Mac drivers in sync with Windows and there are actual third-party vendors who wrap freeware and JDBC drivers inside of ODBC "shells" without warning their customers! This problem is of great concern to developers because fake drivers almost always fly past the IT guys who test with speed deamon desktops, but fail the enterprise when user laptops and iMacs take too long to run queries or slowly corrupt the database when they do. IT guys often chalk this up to "network problems" leaving users with poison drivers to avoid their database. ODBC Router addresses this issue by enabling official vendor supported Windows ODBC drivers (on a Windows Server) to be accessed from all platforms, network wide.

ODBC 3.x?

It's not here yet. Even in 2010, most ODBC drivers are ODBC 1.x and 2.x. The ODBC Driver Manager translates between 3.x and 2.x or 2.x and 1.x ODBC calls. Therefore, if you don't need UNICODE, it's a bad idea to use ODBC 3.x API calls. That said, UNICODE is a Good Thing and there are actually at least three databases that natively support it now, so look for 3.x to be here soon.

Need ODBC API Help?

We really know ODBC and we routinely provide code-level ODBC help to our customers. Our low cost ODBC Router systems are available now at our online store and if your site buys them, you may open a ticket to ask ODBC development questions --we offer both E-Mail and On-Call support options in seven of the G8's timezones! Be sure to test your ODBC Router and ask for any needed installation help before purchase because we aren't Fry's --no refunds please, our prices are too low for such nonsense and we're too busy supporting real Customers!