Handles | DB2(R) Universal Database for OS/390 V7.1 Application Certification Guide (IBM DB2 Certification Guide Series)


Team-Fly

	DB2 Universal Database for OS/390 v7.1 Application Certification Guide By Susan Lawson
	Table of Contents

	Chapter 11. ODBC/CLI Programming

Handles

Handles provide a context between an application program and the ODBC service routines. Each handle is a variable that indirectly references an ODBC controlled data object. These data objects hold information stored as attributes along with internal information used by the DB2 ODBC driver code. Attributes define the behavior expected of the data objects and allow a program some control over that behavior.

Handle Allocation

There are three handle types. All three types of handles are allocated using the SQLAllocHandle() function.

 SQLRETURN SQLAllocHandle (SQLSMALLINT HandleType,                            SQLHANDLE   InputHandle,                           SQLHANDLE  *OutputHandlePtr);

The function requires the type of handle to be allocated, an input handle to establish the context for the new handle, and returns the new handle into an integer buffer (OutputHandlePtr) supplied by the calling program. The SQLAllocHandle() function is part of the ODBC 3.0 specification and is the preferred method of allocating all handles.

Multiple connection and statement handles can be allocated by an application at the same time. DB2 ODBC 3.0 driver applications can use the same environment, connection, or statement handle on different threads. DB2 ODBC provides thread-safe access for all handles and function calls. Applications can have multiple connections to the same or different data sources at the same time and each connection maintains its own unit of recovery. The application itself might experience unpredictable behavior if the threads it creates do not coordinate their use of DB2 ODBC resources.

Environment Handle

The environment handle refers to an environment data object. This data object stores global information about the state of the application, including global attributes and connection settings. Allocation of the environment handle is the first step in an ODBC program and DB2 ODBC uses this opportunity to load the DLL support library and read the initialization file.

The environment handle is allocated by calling SQLAllocHandle() with HandleType set to SQL_HANDLE_ENV and InputHandle set to SQL_NULL_HANDLE. The application passes the *OutputHandlePtr value in all subsequent calls that require an environment handle argument. DB2 ODBC does not support multiple environments. An application program may allocate only one environment handle.

Connection Handle

Connection handles refer to connection data objects. There is a connection data object for each data source used by an application. ODBC data sources are essentially the equivalent of DB2 for OS/390 and z/OS subsystems. An environment handle must be allocated before a connection handle can be allocated. Allocation of the connection handle does not perform the actual connection to the data source, but merely establishes the data object that will store the connection settings including options, status, and diagnostic information. Transaction status is also stored in the connection data object.

The connection handle is allocated by calling SQLAllocHandle() with HandleType set to SQL_HANDLE_DBC and InputHandle set to the environment handle returned in the prior SQLAllocHandle() call. The application passes the *OutputHandlePtr value in all subsequent calls that require a connection handle argument.

By allocating additional connection handles, an application can connect to multiple data sources or establish multiple concurrent connections to the same data source. There may be a limit on the number of connection handles. This limit can be determined with the SQLGetInfo() function. Once a connection handle has been allocated, the SQLConnect() function can be used to connect to DB2 or another DRDA application server.

Statement Handle

Statement handles refer to statement data objects. Each statement data object contains information, attributes, and options about a particular SQL statement. A connection handle must be allocated before a statement handle can be allocated.

A statement handle is allocated by calling SQLAllocHandle() with HandleType set to SQL_HANDLE_STMT and InputHandle set to the appropriate connection handle. Since a connection handle is required, an application can only use this statement handle against a single data source. If you want to run a statement against multiple data sources, you must allocate a statement handle for each data source and make the same calls for each.

Handle Deallocation

Handles are deallocated using the SQLFreeHandle() function. Both the handle type and the handle must be supplied.

 SQLRETURN SQLFreeHandle (SQLSMALLINT HandleType,                           SQLHANDLE   Handle);

Statement handles should be deallocated when they are no longer needed. All statement handles for a connection should be freed before the connection handle. Disconnect from the database using SQLDisconnect() to terminate the database connection before freeing a connection handle. All connection handles should be freed before the environment handle. Finally, the environment handle should be deallocated prior to program termination.

Attributes

Each data object referenced by a handle has several attributes. Attributes are retrieved and manipulated using GET and SET functions. Each handle type has its own specific functions. Attributes are set and retrieved using keyword and value pairs. For environment handles, use

 SQLRETURN SQLGetEnvAttr (SQLHENV     EnvironmentHandle,                           SQLINTEGER  Attribute,                          SQLPOINTER  ValuePtr,                          SQLINTEGER  BufferLength,                          SQLINTEGER *StringLengthPtr) SQLRETURN SQLSetEnvAttr (SQLHENV     EnvironmentHandle,                          SQLINTEGER  Attribute,                          SQLPOINTER  ValuePtr,                          SQLINTEGER  StringLength)

For connection handles, use

 SQLRETURN SQLGetConnectAttr (SQLHDBC     ConnectionHandle,                               SQLINTEGER  Attribute,                              SQLPOINTER  ValuePtr,                              SQLINTEGER  BufferLength,                              SQLINTEGER *StringLengthPtr); SQLRETURN SQLSetConnectAttr (SQLHDBC     ConnectionHandle,                              SQLINTEGER  Attribute,                              SQLPOINTER  ValuePtr,                              SQLINTEGER  StringLength);

For statement handles, use

 SQLRETURN SQLGetStmtAttr (SQLHSTMT    StatementHandle,                            SQLINTEGER  Attribute,                           SQLPOINTER  ValuePtr,                           SQLINTEGER  BufferLength,                           SQLINTEGER *StringLengthPtr); SQLRETURN SQLSetStmtAttr (SQLHSTMT    StatementHandle,                           SQLINTEGER  Attribute,                           SQLPOINTER  ValuePtr,                           SQLINTEGER  StringLength);

Access to an attribute requires a handle. Some environment attributes provide global default values for use across connections and may be overridden for a specific connection by setting the connection attribute. Default attributes are loaded from the initialization file.


Team-Fly

Top