To communicate with a data source, your ESL application must establish a connection with a driver through EDS. EDS returns handles which reference data structures which store information pertinent to the environment. There are three types of handles that are referenced in EDS calls:
•The environment handle identifies a structure used for global information, including valid connection handles and currently active connections. There is one environment structure per application. Your application must allocate an environment handle prior to connecting to a data source.
•The connection handle identifies a structure used to store information about a specific connection. There can be many of these for each application. Your application must allocate a connection handle prior to connecting to a data source.
•The statement handle identifies a structure used to store information about a SQL statement. Your application must allocate a statement handle prior to submitting a SQL request.
Each statement structure is associated with one connection structure. Each connection handle can, however, have multiple statement handles associated with it. There can be one environment handle per task. Each environment handle may have any number of connection handles, and each connection handle may have any number of statement handles (as indicated by the ellipses in Figure 2-3). This relationship is illustrated in Figure 2-3.
Figure 2-3 EDS Handle Structure
The Figure 2-4 illustrates the sequence of EDS commands that are necessary to establish a connection to the data source. The following sections explain how to create the handle structures. Note that you will follow a similar set of steps in reverse order to terminate the connection after SQL statement processing.
Figure 2-4:Establishing a Connection
Environment Handle
Before your application can use any EDS command, it must initialize the EDS interface to ODBC and associate a handle with the environment. To initialize the interface and allocate an environment handle, you must:
1. Declare an ESL integer variable to contain the environment handle.
2. Call EDSAllocEnv and pass the variable to it. The driver initializes the EDS environment and returns the environment handle in the variable.
Your application needs to perform these steps only once, because there can be only one environment handle active per application.
Connection Handle
Before your application can connect to a driver, it must allocate a connection handle for the connection. To allocate a connection handle, you must:
1. Declare an ESL integer variable to contain the connection handle.
2. Call EDSAllocConnect and pass the variable. The driver returns the connection handle in the variable.
Making the Connection
After allocating the connection handle, specify a data source.
Note that each data source relies on a specific driver.
Pass the following information to the driver in a call to EDSConnect:
•Data source name -The name of the data source being requested by the application.
•User ID -The login ID or account name for access to the data source, if appropriate (optional).
•Password -A character string associated with the user ID that allows access to the data source (optional).
When your ESL application calls EDSConnect, the Driver Manager uses the data source name to read the name of the driver DLL from the Windows Registry. It then loads the driver DLL and passes the EDSConnect arguments to it.
EDS High Level Alternative
EDSInit calls the EDS allocation commands EDSAllocEnv, EDSAllocConnect, and EDSAllocStmt, and the connection command EDSConnect. EDSInit returns the environment handle, a connection handle, and a statement handle to an active connection. (For more information about statement handles, refer to Executing SQL Statements.)
