Defining 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 as follows:

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

The following handles are used in essentially all ODBC applications.

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

The following code illustrates how to allocate an environment handle:
```
SQLHENV env; 
SQLRETURN rc; 
rc = SQLAllocHandle( SQL_HANDLE_ENV,
       SQL_NULL_HANDLE, &env );
```
Connection A connection is specified by an ODBC driver and a data source. 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.

The following code illustrates how to allocate a connection handle:
```
SQLHDBC  dbc; 
SQLRETURN rc; 
rc = SQLAllocHandle( SQL_HANDLE_DBC, env, &dbc );
```
Statement A statement handle 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 both for cursor operations (fetching data) and for single statement execution (such as INSERT, UPDATE, and DELETE).

The following code illustrates how to allocate a statement handle:
```
SQLHSTMT stmt; SQLRETURN rc; 
rc = SQLAllocHandle( SQL_HANDLE_STMT, dbc, &stmt );
```
Descriptor A descriptor is a collection of metadata that describes the parameters of an SQL statement or the columns of a result set, as seen by the application or driver (also known as the implementation). 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.
The following example illustrates how to retrieve implicitly allocated descriptors:
```
SQLRETURN rc;
SQLHDESC aparamdesc;
SQLHDESC aparamdesc;
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).