Call Level Interface Guide and Reference

Handles

The initialization task consists of the allocation and initialization of environment and connection handles (which are later freed in the termination task). An application then passes the appropriate handle when it calls other DB2 CLI functions. A handle is a variable that refers to a data object controlled by DB2 CLI. Using handles relieves the application from having to allocate and manage global variables or data structures, such as the SQLDA or SQLCA, used in IBM's embedded SQL interfaces.

The SQLAllocHandle() function is called with with a handle type and parent handle arguments to create environment, connection, statement, or descriptor handles. The function SQLFreeHandle() is used to free the resources allocated to a handle.

There are four types of handles:

Environment Handle

The environment handle refers to the data object that contains information regarding the global state of the application, such as attributes and connections. An environment handle must be allocated before a connection handle can be allocated.

Connection Handle

A connection handle refers to a data object that contains information associated with a connection to a particular data source (database). This includes connection attributes, general status information, transaction status, and diagnostic information.

An application can be connected to several servers at the same time, and can establish several distinct connections to the same server. An application requires a connection handle for each concurrent connection to a database server. For information on multiple connections, refer to "Connecting to One or More Data Sources".

Call SQLGetInfo() to determine if a user imposed limit on the number of connector handles has been set.

Statement Handle(s)

Statement handles are discussed in the next section, "Transaction Processing".

Descriptor Handle(s)

A descriptor handle refers to a data object that contains information about:

• columns in a result set
• dynamic parameters in an SQL statement

Descriptors and descriptor handles are discussed in the section "Using Descriptors".

[ DB2 List of Books | Search the DB2 Books ]