Core subroutine
Load driver and establish a connection to a data source.
call EDSConnect(HDBC_IV, DSN_SV, UID_SV, PASSWORD_SV )
•HDBC_IV An integer input value that indicates the connection handle.
•DSN_SV A string input value that contains the data source name.
•UID_SV A string input value that contains the user identifier (often, the username).
•PASSWORD_SV A string input value that contains the authentication string (typically the password).
Description
Your application can establish more than one connection. The connection handle references all information about the connection, including status, transaction state, and error information. The driver keeps track of which connection is active and switches connections when necessary.
The contents of DSN_SV affect how the Driver Manager and a driver work together to establish a connection to a data source. The Driver Manager uses the following guidelines:
•If DSN_SV contains a data source name, the Driver Manager locates the corresponding data source specification in the Windows Registry and loads the associated driver DLL. The Driver Manager passes each EDSConnect argument to the driver.
•If the corresponding data source specification does not exist, the Driver Manager locates the default data source specification and loads the associated driver DLL. The Driver Manager passes the application-specified data source name to the default driver.
•If DSN_SV contains a data source name but no corresponding data source specification exists and no default data source specification exists, the Driver Manager returns an error.
•If DSN_SV is null, the Driver Manager attempts to locate the default data source specification in the Windows Registry. If the default specification exists, the Driver Manager loads the associated driver DLL and uses "default" as the data source name.
•If no default specification exists, the Driver Manager returns an error.
A driver, upon being loaded by the Driver Manager, can locate the data source specification in the Windows Registry and use driver-specific information from the specification.
Return Values
EDSConnect returns EDS_SUCCESS, EDS_SUCCESS_WITH_INFO, EDS_INVALID_HANDLE, or EDS_ERROR.
When EDSConnect returns EDS_ERROR, you can obtain an associated SQLSTATE value with more specific information by calling EDSError. The following table lists each typical SQLSTATE value and explains each one in the context of the command EDSConnect.
The following table lists possible SQLSTATE values.
SQL STATE |
Error |
Description |
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 |
The value specified for the argument UID_SV or the value specified for the argument PASSWORD_SV violated restrictions defined by the data source. |
IM001 |
Driver does not |
The driver specified by the data source name support this does not support the function. function |
IM002 |
Data source not found and no default driver |
The data source name specified in the argument DSN_SV was not found in the ODBC initialization file nor was there a default driver specified 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 EDSConnect, the Driver Manager called the driver’s EDSAllocEnv function and the driver returned an error. |
IM005 |
Driver’s EDSAllocConnect failed |
During EDSConnect, the Driver Manager called the driver’s EDSAllocConnect function and the driver returned an error. |
IM006 |
Driver’s EDSSetConnect Option failed |
During EDSConnect, the Driver Manager called -the driver’s EDSSetConnectOption function and the driver returned an error. (Function returns EDS_SUCCESS_WITH_INFO.) |
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 the 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
EDSAllocConnect initializes a connection handle.
EDSAllocStmt allocates a statement handle.
EDSDisconnect closes a connection (the opposite of EDSConnect).
EDSDriverConnect establishes a connection using a connection string.
