f90SQLBrowseConnect (SQLBrowseConnect)

Conformance

Version Introduced: ODBC 1.0

Standards Compliance: ODBC

Summary

f90SQLBrowseConnect supports an iterative method of discovering and enumerating the attributes and attribute values required to connect to a data source. Each call to f90SQLBrowseConnect 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 f90SQLBrowseConnect. A return code of SQL_SUCCESS or SQL_SUCCESS_WITH_INFO indicates that all connection information has been specified and the application is now connected to the data source.

Syntax

Arguments

ConnectionHandle [Input]

Connection handle.

InConnectionString [Input]

Browse request connection string (see "InConnectionString Argument" in "Comments").

OutConnectionString [Output]

Buffer in which to return the browse result connection string (see "OutConnectionString Argument" in "Comments").

OutConnectionStringLength [Output]

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 Len(OutConnectionString), the connection string in OutConnectionString is truncated to Len(OutConnectionString) minus the length of a null-termination character.

iRet [Output]

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_ERROR, or SQL_INVALID_HANDLE.

Diagnostics

When f90SQLBrowseConnect returns SQL_ERROR, SQL_SUCCESS_WITH_INFO, or SQL_NEED_DATA, an associated SQLSTATE value may be obtained by calling f90SQLGetDiagRec with a HandleType of SQL_HANDLE_STMT and a Handle of ConnectionHandle. The following table lists the SQLSTATE values commonly returned by f90SQLBrowseConnect 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

InConnectionString Argument

A browse request connection string has the following syntax:

connection-string ::= attribute[;] | attribute; connection-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. Because of the grammar in the system information, keywords and data source names cannot contain the backslash (\) character. For an ODBC 2.x driver, braces are required around the attribute value for the DRIVER keyword.

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

OutConnectionString Argument

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 [:localized-character string] | character-string [:localized-character string], attribute-value-list

where character-string and localized-character string have zero or more characters; identifier and localized-identifier have one or more characters; attribute-keyword is not case-sensitive; and attribute-value may be case-sensitive. Because of connection string and initialization file grammar, keywords, localized identifiers, and attribute values that contain the characters []{}(),;?*=!@ should be avoided. Because of the grammar in the system information, keywords and data source names cannot contain the backslash (\) character.

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 f90SQLBrowseConnect.

• The attribute keywords UID and PWD have the same meaning as defined in f90SQLDriverConnect.

• 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, or 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 by the 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 example, UID=JohnS; PWD=Sesame.

• Each call to f90SQLBrowseConnect 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 determined on each call.

Using f90SQLBrowseConnect

f90SQLBrowseConnect requires an allocated connection. The Driver Manager loads the driver that was specified in or that corresponds to the data source name specified in the initial browse request connection string; for information about when this occurs, see the "Comments" section in f90SQLConnect. It may establish a connection with the data source during the browsing process. If f90SQLBrowseConnect returns SQL_ERROR, outstanding connections are terminated and the connection is returned to an unconnected state.

Note: f90SQLBrowseConnect does not support connection pooling. If f90SQLBrowseConnect is called while connection pooling is enabled, SQLSTATE HY000 (General error) will be returned.

When f90SQLBrowseConnect is called for the first time on a connection, 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 system information:

• If the Driver Manager finds the corresponding data source specification, it loads the associated driver DLL; the driver can retrieve information about the data source from the system information.

• 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 system information. "DEFAULT" is passed to the driver for the DSN.

• 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 browse 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 system information. 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 browse request connection strings.

On each call to f90SQLBrowseConnect, the application specifies the connection attribute values in the browse request connection string. The driver returns successive levels of attributes and attribute values in the browse result connection 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 f90SQLBrowseConnect. All mandatory attributes (those not preceded by an asterisk in the OutConnectionString argument) must be included in the next call to f90SQLBrowseConnect. 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 f90SQLDriverConnect with the SQL_DRIVER_NOPROMPT option to establish another connection. The complete connection string cannot be used in another call to f90SQLBrowseConnect, however; if f90SQLBrowseConnect were called again, the entire sequence of calls would have to be repeated.

f90SQLBrowseConnect also returns SQL_NEED_DATA if there are recoverable, nonfatal errors during the browse process; for example, an invalid password or 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 can call f90SQLGetDiagRec to return the SQLSTATE for browse-time errors. This permits the application to correct the attribute and continue the browse.

An application can terminate the browse process at any time by calling f90SQLDisconnect. The driver will terminate any outstanding connections and return the connection to an unconnected state.

If a driver supports f90SQLBrowseConnect, the driver keyword section in the system information for the driver must contain the ConnectFunctions keyword with the third character set to "Y."

Code Example

In the following example, an application calls f90SQLBrowseConnect repeatedly. Each time f90SQLBrowseConnect returns SQL_NEED_DATA, it passes back information about the data it needs in OutConnectionString. The application passes OutConnectionString to its routine GetUserInput (not shown). GetUserInput parses the information, builds and displays a dialog box, and returns the information entered by the user in InConnectionString. The application passes the user's information to the driver in the next call to f90SQLBrowseConnect. After the application has provided all necessary information for the driver to connect to the data source, f90SQLBrowseConnect returns SQL_SUCCESS and the application proceeds.

For example, to connect to the data source Sales, the following actions might occur. First, the application passes the following string to f90SQLBrowseConnect:

"DSN=Sales"

The Driver Manager loads the driver associated with the data source Sales. It then calls the driver's f90SQLBrowseConnect function with the same arguments it received from the application. The driver returns the following string in OutConnectionString:

"HOST:Server={red,blue,green};UID:ID=?;PWD:Password=?"

The application passes this string to its GetUserInput routine, which builds a dialog box that asks the user to select the red, blue, or green server, and to enter a user ID and password. The routine passes the following user-specified information back in InConnectionString, which the application passes to f90SQLBrowseConnect:

"HOST=red;UID=Smith;PWD=Sesame"

f90SQLBrowseConnect uses this information to connect to the red server as Smith with the password Sesame, and then returns the following string in OutConnectionString:

"*DATABASE:Database={SalesEmployees,SalesGoals,SalesOrders}"

The application passes this string to its GetUserInput routine, which builds a dialog box that asks the user to select a database. The user selects empdata and the application calls f90SQLBrowseConnect a final time with this string:

"DATABASE=SalesOrders"

This is the final piece of information the driver needs to connect to the data source; f90SQLBrowseConnect returns SQL_SUCCESS and OutConnectionString contains the completed connection string:

"DSN=Sales;HOST=red;UID=Smith;PWD=Sesame;DATABASE=SalesOrders"

Related Subroutines