Level 2 subroutine
Determine the attributes required to connect to a data source.
call EDSBrowseConnect(HDBC_IV, CONNSTRIN_SV, CONNSTROUT_SV )
•HDBC_IV An integer input value indicating the connection handle.
•CONNSTRIN_SV A string input value containing the browse request connection string.
•CONNSTROUT_SV A string output value containing the browse result connection string.
Description
EDSBrowseConnect supports an iterative method of discovering and enumerating the attributes and attribute values required to connect to a data source. Each time your application calls EDSBrowseConnect, the command returns successive levels of attributes and attribute values. When all levels have been enumerated, EDSBrowseConnect connects to the data source and returns a complete connection string. EDSBrowseConnect returns EDS_SUCCESS or EDS_SUCCESS_WITH_INFO to indicate that all connection information has been specified and your application is now connected to the data source.
When your application calls EDSBrowseConnect for the first time on a connection, the Driver Manager uses the browse request connection string to locate a corresponding data source specification in the Windows Registry.
•If the Driver Manager finds the corresponding data source specification, it loads the associated driver DLL.
•If the Driver Manager cannot find the corresponding data source specification, it locates the default data source specification and loads the associated driver DLL.
•If the Driver Manager cannot find the corresponding data source specification and there is no default data source specification, it returns EDS_ERROR with SQLSTATE IM002.
Each call to EDSBrowseConnect returns EDS_NEED_DATA as long as there are connection attributes that have not yet been enumerated in the browse request connection string. When all levels of connection and their associated attributes have been enumerated, the driver returns EDS_SUCCESS, the connection to the data source is complete, and a complete connection string is returned to your application. You can then pass the connection string to EDSDriverConnect with the EDS_DRIVER_NOPROMPT option to establish another connection.
EDSBrowseConnect also returns EDS_NEED_DATA if there are recoverable, non-fatal errors during the browse process; for example, an invalid password supplied by your application or an invalid attribute keyword supplied by your application. When EDS_NEED_DATA is returned and the browse result connection string is unchanged, an error has occurred and your application must call EDSError to return the SQLSTATE for browse-time errors. This permits your application to correct the attribute and continue the browse.
Your application may terminate the browse process at any time by calling EDSDisconnect. EDS will terminate any outstanding connections and return HDBC_IV to an unconnected state.
If EDSBrowseConnect returns EDS_ERROR, outstanding connections are terminated and HDBC_IV is returned to an unconnected state.
A connection string has the following format:
DSN=data-source-name;UID[n]=userID;PWD[n]=password;[DBQ=database-qualifier;] [UIDn=userID;PWDn=password...][attribute=value]
The keywords UID_SV and PWD_SV are optional. The ellipsis indicates that you can specify additional userIDs and keywords. The keyword DSN_SV is optional on input if DRIVERCOMPLETION_IV is EDS_DRIVER_PROMPT, EDS_DRIVER_COMPLETE, or EDS_DRIVER_COMPLETE_REQUIRED. The connection string may include any number of driver-defined keywords. The following table describes the attribute values of the DSN_SV, UID_SV, and PWD_SV keywords.
Argument |
Description |
data-source-name |
Name of a data source as returned by EDSDataSources or the data sources dialog box of EDSDriverConnect. |
UID[n] |
The n indicates the number of the userID, starting with 1. If there is only one userID and password, the 1 can be omitted. |
userID |
A user identifier. |
PWD[n] |
The n indicates then umber of the password, starting with 1. |
password |
The password corresponding to the nth user ID, or NULL if there is no password for the userID. |
database-qualifier |
The driver-dependent qualifier, such as the database name, if the data source supports a database qualifier. |
attribute |
Driver-defined connection attribute (optional). |
value |
Driver-defined attribute value (optional). |
The 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 EDSBrowseConnect.
•The attribute keywords DSN, UID, and PWD, have the same meaning as defined in EDSDriverConnect.
•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". The driver-defined-attribute-keyword includes a localized or "user-friendly" version of the keyword. For example, this should be used by applications that will display this text as a label in a dialog box. However, 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. 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=JaneT; PWD=MET.
•Each call to EDSBrowseConnect returns only the information required to satisfy the next level of the connection process.
EDSBrowseConnect returns EDS_SUCCESS, EDS_SUCCESS_WITH_INFO, EDS_NEED_DATA, EDS_INVALID_HANDLE, or EDS_ERROR.
The following table lists possible SQLSTATE values.
SQL STATE |
Error |
Description |
01004 |
Data truncated |
The browse result connection string returned in the argument CONNSTROUT_SV was truncated. |
01S00 |
Invalid connection string attribute |
An invalid attribute keyword was specified in the browse request connection string (CONNSTRIN_SV). (Function returns SQL_NEED_DATA.) |
08001 |
Unable to connect to data source |
The driver was unable to establish a connection with the data source. |
08002 |
Connection in use |
The specified connection handle had already been used to establish a connection with a data source and the connection was still open. |
08004 |
Data source rejected establishment of 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 browse request connection string (CONNSTRIN_SV), violated restrictions defined by the data source. |
IM001 |
Driver does not support this function |
The driver corresponding to the specified data source name does not support the function. |
IM002 |
Data source not found and no default driver specified |
The data source name specified in the browse request connection string (CONNSTRIN_SV) was not found in the ODBC initialization file nor was there a default driver specification. The ODBC initialization file could not be found. |
IM003 |
Driver specified by data source could not be loaded |
The driver specified in the data source specification associated with the data source name in the ODBC initialization file was not found or could not be loaded for some other reason. |
IM004 |
Driver’s EDSAllocEnv failed |
During EDSBrowseConnect, the Driver Manager called the driver’s EDSAllocEnv function and the driver returned an error. |
IM005 |
Driver’s EDSAllocConnect failed |
During EDSBrowseConnect, the Driver Manager called the driver’s EDSAllocConnect function and the driver returned an error. |
IM006 |
Driver’s EDSSetConnect Option failed |
During EDSBrowseConnect, the Driver Manager called the driver’s EDSSetConnectOption function and the driver returned an error. |
S1000 |
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 EDSError in the argument ERRORTEXT describes the error and its cause. |
S1001 |
Memory allocation failure |
The Driver Manager or driver was unable to allocate memory required to support execution or completion of the function. |
S1T00 |
Timeout expired |
The timeout period expired before the connection to the data source completed. The timeout period is set through EDSSetConnectOption, EDS_LOGIN_TIMEOUT. |
See Also
EDSDriverConnect connects to a data source.
EDSAllocConnect allocates a connection handle.
EDSDisconnect disconnects from a data source.
EDSFreeConnect frees a connection handle.
