Allocating a connection handle

Before a connection to a data source can be established, the application must allocate a connection handle. This is a process similar to allocating an environment handle. An environment can have more than one connection handle allocated.

To allocate a connection handle, the application uses f90SQLAllocHandle with the option SQL_HANDLE_DBC and passes the current environment handle as an argument. The following example allocates a connection handle. Its address is stored in the variable ConnHndl:

It is important to note that allocating a connection handle is not the same as loading a driver. The driver is not loaded until a connection is requested (using f90SQLConnect, for example). Thus, after allocating a connection handle and before connecting to the driver or data source, the only subroutines the application can call with the connection handle are f90SQLSetConnectAttr, f90SQLGetConnectAttr, or f90SQLGetInfo with the SQL_ODBC_VER option. Calling other functions with the connection handle, such as f90SQLEndTran will return an error status in parameter iRet.

Once a connection handle has been allocated, the application can set some connection attributes. Connection attributes are characteristics of the connection. For example, because transactions occur at the connection level, the transaction isolation level is a connection attribute. Similarly, the login timeout, i.e. the number of seconds to wait while trying to connect before timing out, is a connection attribute.

Connection attributes are set with f90SQLSetConnectAttr and their current settings retrieved with f90SQLGetConnectAttr. If f90SQLSetConnectAttr is called before the driver is loaded, the Driver Manager stores the attributes in its connection structure and sets them in the driver as part of the connection process. There is no requirement that an application set any connection attributes. All connection attributes have defaults, some of which are driver specific.

Some connection attributes can be set before the connection is established. Others can be set after, or either before and after, the connection is established. This depends on the attribute and the driver. The login timeout (SQL_ATTR_LOGIN_TIMEOUT) applies to the connection process and is effective only if set before connecting. The attributes that specify whether to use the ODBC cursor library (SQL_ATTR_ODBC_CURSORS) and the network packet size (SQL_ATTR_PACKET_SIZE) must also be set before connecting. The reason for this is that the ODBC cursor library resides between the Driver Manager and the driver. Therefore it must be loaded before the driver.

To set pre-connection attributes, the application calls the subroutine f90SQLSetConnectAttr. This subroutine is called with the same convention explained for f90SQLSetEnvAttr. For example, the following calls enable the tracing feature of a connection whose handle is stored in variable ConnHndl. When tracing is enable, the driver logs all ODBC operations into a trace file. The first call to f90SQLSetConnectAttr tells the driver the name and location of the file where the log must be stored. The second call to f90SQLSetConnectAttr enables the log (this attribute is disabled by default):

If the log file already exists, the driver will append the new logs to the old file. If the file does not exist, the driver will create it.