Allocating Handles

SQL API lets an application manage interactions with data sources through handles. There are four types of SQL API handles.

Environment Handle

An environment handle is the base handle that manages global resources and options for an application. An application can call SQLAllocHandle() using SQL_HANDLE_ENV as the first argument in order to allocate an environment handle. An application must allocate an environment handle in order to access an RDM data source. Multiple environment handles can be allocated inside an application.

Connection Handle

A connection handle is the handle that manages resources and options specific to a connection to a data source. An application can call SQLAllocHandle() using SQL_HANDLE_DBC as the first argument and an existing environment handle as the second in order to allocate a connection handle. An application must allocate a connection handle in order to access an RDM data source. An application can allocate multiple connection handles on one environment handle in order to manage multiple connections to the same or different data sources. In a multi-thread environment, SQL API requires that each thread have its own connection handle.

Statement Handle

A statement handle is the handle that manages resources and options specific to a particular SQL statement operation. An application can call SQLAllocHandle() using SQL_HANDLE_STMT as the first argument and an existing connection handle as the second in order to allocate a statement handle. An application must allocate a statement handle in order to execute SQL statements against an RDM data source. An application can allocate multiple statement handles on one connection handle in order to execute different SQL statements on one data source. Operations such as positioned update and delete require the use of multiple statement handles on one connection.

Descriptor Handle

A descriptor handle is the handle that manages the detailed characteristics and information both an application and SQL API use internally. There are two types of descriptors: application descriptors and implementation descriptors. An application descriptor stores information an application maintains for its operations. An implementation descriptor stores information SQL API uses internally. Both application and implementation descriptors have two subcategories: parameter descriptors and row descriptors. Together, there are four types of descriptor handles as below.

Type		Description
Application Parameter Descriptor	APD	An APD maintains information about a dynamic parameter an application uses when executing an SQL statement.
Application Row Descriptor	ARD	An ARD maintains information about a row/column returned to an application when it fetches data from a data source.
Implementation Parameter Descriptor	IPD	An IPD maintains information about a dynamic parameter SQL API uses internally when an application executes an SQL statement.
Implementation Row Descriptor	IRD	An IRD maintains information about a row/column defined on a data source from which an application fetches data.

All the four descriptors are implicitly allocated by SQL API. An application can explicitly allocate application descriptors (APD and ARD) by calling SQLAllocHandle() using SQL_HANDLE_DESC as the first argument and an existing connection handle as the second, and instructs SQL API to use them instead of the implicitly-allocated descriptors. Descriptors explicitly allocated by an application cannot be used as implementation descriptors (IPD and IRD).

The following example illustrates how to allocate SQL API handles using SQLAllocHandle().

Example 1. Allocating handles

#include "sqlext.h"int main (void){    SQLRETURN rc;    SQLHENV hEnv;    SQLHDBC hDbc;    /* Allocate an environment handle */    rc = SQLAllocHandle (SQL_HANDLE_ENV, NULL, &hEnv);    if (SQL_SUCCEEDED (rc))    {        /* Allocate a connection handle */        rc = SQLAllocHandle (SQL_HANDLE_DBC, hEnv, &hDbc);        if (SQL_SUCCEEDED (rc))        {            /* Connect to the local data source. The code for               connectToDataSource is shown in the next               section */            rc = connectToDataSource (hDbc);            if (SQL_SUCCEEDED (rc))            {                /* Do some database operations */                rc = runDbOperations (hDbc);                (void) SQLDisconnect (hDbc);            }            (void) SQLFreeHandle (SQL_HANDLE_DBC, hDbc);        }        (void) SQLFreeHandle (SQL_HANDLE_ENV, hEnv);    }    return 0;}