A connection consists of a driver and a data source. A connection handle is a pointer to a data structure which contains information about a data source connection being managed by the ODBC Driver Manager. The connection handle defines not only which driver to use, but also what data source to use with that driver. The Driver Manager, uses the connection handle to store information including:
Connection handles are allocated inside the data storage area of the environment handle. ODBC does not prevent multiple simultaneous connections if the driver supports them. Thus, in a particular ODBC environment, multiple connection handles might point to a variety of drivers and data sources, the same driver and a variety of data sources, or even multiple connections to the same driver and data source. Some drivers limit the number of active connections they support. The maximum number of connections supported by a driver can be found by calling the subroutine f90SQLGetInfo with the option SQL_MAX_DRIVER_CONNECTIONS.
Connection handles are used primarily when connecting to the data source (subroutines f90SQLConnect, f90SQLDriverConnect, or f90SQLBrowseConnect), disconnecting from the data source (f90SQLDisconnect), getting information about the driver and data source (f90SQLGetInfo), retrieving diagnostics (f90SQLGetDiagField and f90SQLGetDiagRec), and performing transactions (f90SQLEndTran). They are also used when setting and getting connection attributes (f90SQLSetConnectAttr and f90SQLGetConnectAttr) and when getting the native format of an SQL statement (f90SQLNativeSql).
As is the case for environment handles, connection handles must be allocated by calling the subroutine f90SQLAllocHandle and terminated by calling subroutine f90SQLFreeHandle. The following Fortran program builds on Example 4.2. It requests a list of the first 10 data sources and then allows the user to select which one he wants to connect with. After the selection has been made, the program allocates a connection handle and establishes a connection to the data source. The connection is established using the subroutine f90SQLDriverConnect. This is described in more details later, but to help you understand the example, here is a short summary of the parameters passed to the subroutine and what they mean. f90SQLDriverConnect is called as:
| call f90SQLDriverConnect | (ConnHandle, WinHandle, InConnStr, OutConnStr, OutConnStrLength, DriverCompletionOpt, iRet) |
Parameter ConnHandle is the connection handle associated to this data source connection. WinHandle is the parent window's handle. It is not used here. InConnStr is a character variable containing a connection string. A basic connection string may look something like this; "DSN=My DataBase;UID=JDoe;PWD:AbreteSesamo". It contains a data source name, a user ID, a user password, and other additional information necessary to establish the connection to the data source. When f90SQLDriverConnect executes, it returns in OutConnStr a full connection string with its length returned in OutConnStrLength. The parameter DriverCompletionOpt is used by your application to indicate whether the driver should prompt the user for necessary connection information that was not included in InConnStr. f90SQL defines several constants that can be used with this option. For example, the constant SQL_DRIVER_COMPLETE instructs the driver to request missing information. The constant SQL_DRIVER_NOPROMPT tells the driver not to do so. In this last case, if information is missing, the connection is not established.
|