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.

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:

  SQLRETURN rc;
  SQLHENV env;
  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:

  SQLRETURN rc;
  SQLHDBC  dbc;
  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 (for example, INSERT, UPDATE, and DELETE).

  The following code illustrates how to allocate a statement handle:

  SQLRETURN rc;
  SQLHSTMT stmt;
  rc = SQLAllocHandle( SQL_HANDLE_STMT, dbc, &stmt );

• How to allocate ODBC handles
  The handle types required for ODBC programs are as follows:
• ODBC example
  A simple ODBC program that connects to the SAP Sybase IQ sample database and immediately disconnects can be found in %IQDIRSAMP16%\SQLAnywhere\ODBCConnect\odbcconnect.cpp. This example shows the steps required in setting up the environment to make a connection to a database server, as well as the steps required in disconnecting from the server and freeing up resources.