Level 1 subroutine

Establish a connection to a data source requiring extra connection information.

call EDSDriverConnect(HDBC_IV, HWND_IV, CONNSTRIN_SV, CONNSTROUT_SV, DRIVERCOMPLETION_IV ) 

•HDBC_IV An input integer value that indicates the connection handle.

•HWND_IV An input integer value that contains the allocated window handle. Your application can pass the handle of the parent window, if applicable, or NULL if either the window handle is not applicable or if EDSDriverConnect will not present any dialog boxes.

•CONNSTRIN_SV An input string value that contains a full connection string, a partial connection string, or an empty string.

•CONNSTROUT_SV An output string. Upon successful connection to the target data source, this string will be updated to contain the completed connection string.

•DRIVERCOMPLETION_IV An input integer value that indicates EDS_DRIVER_PROMPT, EDS_DRIVER_COMPLETE, EDS_DRIVER_COMPLETE_REQUIRED, or EDS_DRIVER_NOPROMPT. (See "Description", for additional information.

Description

The primary purpose of EDSDriverConnect is to provide the user interface required to make a connection to a data source, including all connection information exposed by the data source and/or network topology (if applicable).

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

Once a connection is established, EDSDriverConnect returns the completed connection string. Your application can use this string for subsequent connection requests to the same driver.

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.

 

The contents of DRIVERCOMPLETION_IV and CONNSTRIN_SV affect how the Driver Manager and a driver work together to establish a connection to a data source.

Driver Manager Guidelines

The value of DRIVERCOMPLETION_IV determines the behavior of the Driver Manager, as follows:

•If the value of the argument DRIVERCOMPLETION_IV is EDS_DRIVER_PROMPT, the Driver Manager initiates a data source dialog. It obtains a data source name from the dialog box. (This name may be an empty string.) The data source name is inserted into the copy of CONNSTRIN_SV that the Driver Manager passes to the driver.

•If the value of the argument DRIVERCOMPLETION_IV is EDS_DRIVER_COMPLETE or EDS_DRIVER_COMPLETE_REQUIRED, and if CONNSTRIN_SV is an empty string or if there is no data source name in the connection string, the Driver Manager initiates a data sources dialog box. It obtains a data source name from the dialog box. (This name may be an empty string.) The data source name is inserted into the copy of CONNSTRIN_SV that the Driver Manager passes to the driver.

•If the value of the argument DRIVERCOMPLETION_IV is EDS_DRIVER_NOPROMPT, the Driver Manager passes a copy of CONNSTRIN_SV to the driver.

•Using the connection string, the Driver Manager attempts 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 (Data source not found and no default driver specified).

Driver Guidelines

The value of CONNSTRIN_SV determines the behavior of the driver, as follows:

•The driver locates the data source specification in the Windows Registry that corresponds to the data source name in CONNSTRIN_SV. If CONNSTRIN_SV is an empty string or the data source name cannot be found, the driver locates the default data source specification.

•The driver uses the information in the Windows Registry, if available, to add driver-specific information to the connection string.

•Depending on the value of DRIVERCOMPLETION_IV, the driver prompts the user for missing information, including user ID, password, and other attributes.

•If DRIVERCOMPLETION_IV equals EDS_DRIVER_PROMPT, the driver always initiates a dialog box with the user. The driver uses information from CONNSTRIN_SV for defaults. For information not included in CONNSTRIN_SV, the driver uses information from the data source specification as defaults.

•If DRIVERCOMPLETION_IV equals EDS_DRIVER_COMPLETE, the driver initiates a dialog box only if there is not enough information in CONNSTRIN_SV to connect to the data source. The driver uses information from CONNSTRIN_SV for defaults. For information not included in CONNSTRIN_SV, the driver uses information from the data source specification as defaults.

•If DRIVERCOMPLETION_IV equals EDS_DRIVER_COMPLETE _REQUIRED, the driver initiates a dialog box only if there is not enough information in CONNSTRIN_SV to connect to the data source. The driver uses information from CONNSTRIN_SV for defaults. For information not included in CONNSTRIN_SV, the driver uses information from the data source specification as defaults. The driver greys and disables any prompts for information that is not required to complete the connection.

•If DRIVERCOMPLETION_IV equals EDS_DRIVER_NOPROMPT, the driver attempts to connect to the data source. The driver does not display a dialog box. If CONNSTRIN_SV is not sufficient, EDSDriverConnect returns EDS_ERROR.

 

Note: The EDS_LOGIN_TIMEOUT connection option, set using EDSSetConnectOption, defines the number of seconds to wait for a login request to complete before returning to your 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 EDS_MODE_READ_WRITE access mode by default. To set the access mode to EDS_MODE_READ_ONLY, your application must call EDSSetConnectOption with the EDS_ACCESS_MODE option prior to calling EDSDriverConnect.

On successful connection to the data source, the driver stores the complete connection string in the buffer referenced by CONNSTROUT_SV and sets CONNSTROUT_SV to the length of the connection string.

In the following example, the application copies the handle of the ESL primary window to HWND_IV.  This allows EDSDriverConnect to identify the parent window for the connection dialog box(es).  The application then specifies the connection string and option and calls EDSDriverConnect.

copy (handle of Primary_GR) to HWND_IV copy "DSN=;UID=;PWD=;" to CONNSTRIN _SV copy EDS_DRIVER_PROMPT to DRIVERCOMPLETION _IV call EDSDriverConnect( HDBC_IV,HWND_IV,CONNSTRIN _SV,CONNSTROUT _SV, DRIVERCOMPLETION _IV)

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

Return Values

EDSDriverConnect returns EDS_SUCCESS, EDS_SUCCESS_WITH_INFO, EDS_NO_DATA_FOUND, EDS_INVALID_HANDLE, or EDS_ERROR.

When EDSDriverConnect 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 EDSDriverConnect.

See Also

EDSAllocConnect allocates a connection handle.
EDSBrowseConnect discovers and enumerates values required to connect to a data source.
EDSConnect connects to a data source.
EDSDisconnect closes a connection to a data source.
EDSFreeConnect frees the connection handle.