SQLBrowseConnect supports an alternative method of discovering and enumerating the attributes and attribute values required to connect to a data source. Each call to SQLBrowseConnect returns successive levels of attributes and attribute values. When all levels have been enumerated, a connection to the data source is completed and a complete connection string is returned by SQLBrowseConnect. A return code of SQL_SUCCESS or SQL_SUCCESS_WITH_INFO indicates that all connection information has been specified and the applicaiton is now connected to the data source.

When SQLBrowseConnect 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 SQLBrowseConnect 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 browse request 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.

If any keywords are repeated in the browse request 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 browse request connection string, the Driver Manager and the driver use whichever keyword appears first.

The browse result connection string is a list of connection attributes. A connection attribute consists of an attribute keyword and a corresponding attribute value. The browse result connection string has the following syntax:

connection-string ::= attribute[;]|attribute; connection-string
attribute ::=[*]attribute-keyword=attribute-value
attribute-keyword := ODBC-attribute-keyword|driver-defined-attribute-keyword
ODBC-attribute-keyword={UID|PWD}[:localized-identifier]
driver-defined-attribute-keyword ::= identifier[:localized-identifier]
attribute-value ::={attribute-value-list}|?
(The braces are literal; they are returned by the driver.)
attribute-value-list ::= character-string|character-string, attribute-value-list

The browse result connection string syntax is used according to the following semantic rules:

• If an asterisk (*) precedes an attribute-keyword, the Attribute is optional, and may be omitted in the next call to SQLBrowseConnect.
• The attribute keywords UID and PWD have the same meaning as defined in SQLDriverConnect.
• A driver-defined-attribute-keyword names the kind of attribute for which an attribute value may be supplied. For example, it might be SERVER, DATABASE, HOST, DBMS.
• ODBC-attribute-keywords and driver-defined-attribute-keywords include a localized or user-friendly version of the keyword. This might be used by applications as a label in a dialog box. However, UID, PWD, or the identifier alone must be used when passing a browse request string to the driver.
• The {attribute-value-list} is an enumeration of actual values valid for the corresponding attribute-keyword. Note that the braces ({}) do not indicate a list of choices; they are returned byt he driver. For example, it might be a list of server names or a list of database names.
• If the Attribute-value is a single question mark (?), a single value corresponds to the attribute-keyword. For exmaple, UID=JohnS; PWD=Sesame.
• Each call to SQLBrowseConnect returns only the information required to satisfy the next level of the connection process. The driver associates state information with the connection handle so that the context can always be determiend on each call.

SQLBrowseConnect requires an allocated hdbc. The Driver Manager loads the driver that was specified in or that corresponds to the data source name specified in the intiial browse request connection string; for information on when this occurs, see the "Comments" section in SQLConnect. It may establish a connection witht he data source during the browsing process. If SQLBrowseConnect returns SQL_ERROR, outstanding connections are terminated and the hdbc is returned to an unconnected stated.

When SQLBrowseConnect is called for the first time on an hdbc, the browse request connection string must contain the DSN keyword or the DRIVER keyword. If the browse request connection string contains the DSN keyword, the Driver Manager locates a corresponding data source specification in the ODBC.INI file or registry:

• If the Driver Manager finds the corresponding data source specification, it loads the associated driver DLL; the driver canr etrieve information about the data source from the ODBC.INI file or registry.
• If the Driver Manager cannot find the corresponding data source specification, it locates the default data source specification and loads the associated driver DLL; the driver can retrieve information about the default data source from the ODBC.INI file or registry.
• If the Driver Manager cannot find the corresponding data source specification and there is no default data source specification, it returns SQL_ERROR with SQLSTATE IM002 (Data source not found and no default driver specified).

If the browser request connection string contains the DRIVER keyword, the Driver Manager loads the specified driver; it does not attempt to locate a data source in the ODBC.INI file or registry. BEcause the DRIVER keyword does not use information from the ODBC.INI file or registry, the driver must define enough keywords so that the driver can connect to a data source using onlyt he information in the browse request connection string.

On each call to SQLBrowseConnect, the application specifies the connection attribute values int he browse request connection string. The driver returns successive levels of attributes and attribute values in the browse result oconnection string; it returns SQL_NEED_DATA as long as there are connection attributes that have not yet been enumerated in the browse request connection string. The application uses the contents of the browse result connection string to build the browse request connection string for the next call to SQLBrowseConnect. Note that the application cannot use the contents of previous browse result connection strings when building the current browse request connection string; that is, it cannot specify different values for attributes set in previous levels.

When all levels of connection and their associated attributes have been enumerated, the driver returns SQL_SUCCESS, the connection to the data source is complete, and a complete connection string is returned to the application. The connection string is suitable to use in conjunction with SQLDriverConnect with the SQL_DRIVER_NOPROMPT option to establish another connection.

SQLBrowseConnect also returns SQL_NEED_DATA if there are recoverable, nonfatal errors during the browse process, for example, an invalid password supplied by the application or an invalid attribute keyword supplied by the application. When SQL_NEED_DATA is returned and the browse result connection string is unchanged, an error has occurred and the application must call SQLError to return the SQLSTATE for browse-time errors. This permits the application to current the attribute and continue the browse.

An application may terminate the browse process at any time by calling SQLDisconnect. The driver will terminate any outstanding connections and return the hdbc to an unconnected state.

If a driver supports SQLBrowseConnect, the driver keyword section of the ODBC.INF file for the driver must contain the ConnectFunctions keyword with the third character set to "Y".

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!