ODBC Handles

ODBC applications use a small set of handles to define basic features, such as database connections and SQL statements.

A handle is a 32-bit value on 32-bit platforms and a 64-bit value on 64-bit platforms. The handle types required for ODBC programs are:

Item	Handle Type
Environment	`SQLHENV`
Connection	`SQLHDBC`
Statement	`SQLHSTMT`
Descriptor	`SQLHDESC`

These handles are used in all ODBC applications:

Environment – provides a global context to access data. Every ODBC application must allocate exactly one environment handle upon starting, and must free it at the end.

This code allocates an environment handle:
```
SQLHENV env; 
SQLRETURN rc; 
rc = SQLAllocHandle( SQL_HANDLE_ENV,
       SQL_NULL_HANDLE, &env );
```
Connection – is specified by an ODBC driver and a datasource. An application can have several connections associated with its environment. Allocating a connection handle does not establish a connection; a connection handle must be allocated first and then used when the connection is established.

This code allocates a connection handle:
```
SQLHDBC  dbc; 
SQLRETURN rc; 
rc = SQLAllocHandle( SQL_HANDLE_DBC, env, &dbc );
```
Statement – provides access to a SQL statement and any information associated with it, such as result sets and parameters. Each connection can have several statements. Statements are used for cursor operations (fetching data) and for single statement execution (such as INSERT, UPDATE, and DELETE).

This code allocates a statement handle:
```
SQLHSTMT stmt; SQLRETURN rc; 
rc = SQLAllocHandle( SQL_HANDLE_STMT, dbc, &stmt );
```
Descriptor – is a collection of metadata that describes the parameters of a SQL statement or the columns of a result set, as seen by the application or driver. Thus, a descriptor can fill any of four roles:
- Application Parameter Descriptor (APD) – contains information about the application buffers bound to the parameters in an SQL statement, such as their addresses, lengths, and C datatypes.
- Implementation Parameter Descriptor (IPD) – contains information about the parameters in a SQL statement, such as their SQL datatypes, lengths, and nullability.
- Application Row Descriptor (ARD) – contains information about the application buffers bound to the columns in a result set, such as their addresses, lengths, and C datatypes.
- Implementation Row Descriptor (IRD) – contains information about the columns in a result set, such as their SQL datatypes, lengths, and nullability.
This example illustrates how to retrieve implicitly allocated descriptors:
```
SQLRETURN rc;
SQLHDESC aparamdesc;
SQLHDESC iparamdesc;
SQLHDESC irowdesc;
SQLHDESC arowdesc;
rc = SQLGetStmtAttr(stmt, SQL_ATTR_APP_PARAM_DESC,
   &aparamdesc, SQL_IS_POINTER);

rc = SQLGetStmtAttr(stmt, SQL_ATTR_APP_ROW_DESC,
   &arowdesc, SQL_IS_POINTER);

rc = SQLGetStmtAttr(stmt, SQL_ATTR_APP_ROW_DESC,
   &iparamdesc, SQL_IS_POINTER);

rc = SQLGetStmtAttr(stmt, SQL_ATTR_APP_ROW_DESC,
   &irowdesc, SQL_IS_POINTER);
```
Implicit descriptors are automatically freed when the statement handle is freed by calling SQLFreeHandle(SQL_HANDLE_STMT, stmt).