`SQLAllocHandle()` - Allocate a handle

SQLAllocHandle() allocates an environment handle, a connection handle, or a statement handle.

ODBC specifications for `SQLAllocHandle()`

Table 1. `SQLAllocHandle()` specifications
ODBC specification level	In X/Open CLI CAE specification?	In ISO CLI specification?
3.0	Yes	Yes

Syntax

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

Function arguments

The following table lists the data type, use, and description for each argument in this function.

Table 2. `SQLAllocHandle()` arguments
Data type	Argument	Use	Description
SQLSMALLINT	HandleType	input	Specifies the type of handle that you want to allocate. Set this argument to one of the following values: SQL_HANDLE_ENV for an environment handle SQL_HANDLE_DBC for a connection handle SQL_HANDLE_STMT for a statement handle
SQLHANDLE	InputHandle	input	Specifies the handle from which you allocate the new handle. You set a different value for this argument depending on what type of handle you allocate. Set the InputHandle argument to one of the following values: SQL_NULL_HANDLE (or ignore this argument) if you are allocating an environment handle To the environment handle if you are allocating a connection handle To a connection handle if you are allocating a statement handle
SQLHANDLE *	OutputHandlePtr	output	Points to the buffer in which `SQLAllocHandle()` returns the newly allocated handle.

Usage

Use SQLAllocHandle() to allocate an environment handle, connection handles, and statement handles.

Allocating an environment handle
An environment handle provides access to global information. To request an environment handle in your application, call SQLAllocHandle()with the HandleType argument set to SQL_HANDLE_ENV and the InputHandle argument set to SQL_NULL_HANDLE. (InputHandle is ignored when you allocate an environment handle.) Db2 ODBC allocates the environment handle and passes the value of the associated handle to the *OutputHandlePtr argument. Your application passes the *OutputHandle value in all subsequent calls that require an environment handle argument.

When you call SQLAllocHandle()to request an environment handle, the Db2 ODBC 3.0 driver implicitly sets SQL_ATTR_ODBC_VERSION = SQL_OV_ODBC3.

When you allocate an environment handle, the Db2 ODBC 3.0 driver checks the trace keywords in the common section of the Db2 ODBC initialization file. If these keywords are set, Db2 ODBC enables tracing. Db2 ODBC ends tracing when you free the environment handle.

The Db2 ODBC 3.0 driver does not support multiple environments.
Allocating a connection handle
A connection handle provides access to information such as the valid statement handles on the connection and an indication of whether a transaction is currently open. To request a connection handle, call SQLAllocHandle()with the HandleType argument set to SQL_HANDLE_DBC. Set the InputHandle argument to the current environment handle. Db2 ODBC allocates the connection handle and returns the value of the associated handle in *OutputHandlePtr. Pass the *OutputHandlePtr in all subsequent function calls that require this connection handle as an argument.

You can allocate multiple connection handles from the context of a single environment handle.
Allocating a statement handle
A statement handle provides access to statement information, such as messages, the cursor name, and status information about SQL statement processing. To request a statement handle, connect to a data source and then call SQLAllocHandle(). You must allocate a statement handle before you submit SQL statements. In this call, set the HandleType argument to SQL_HANDLE_STMT. Set the InputHandle argument to the connection handle that is associated with the connection on which you want to execute SQL. Db2 ODBC allocates the statement handle, associates the statement handle with the connection specified, and returns the value of the associated handle in *OutputHandlePtr. Pass the *OutputHandlePtr value in all subsequent function calls that require this statement handle as an argument.

You can allocate multiple statement handles from the context of a single connection handle.
Managing handles
Your Db2 ODBC applications can allocate multiple connection handles and multiple statement handles at the same time. You can allocate multiple connection handles and make multiple connections only when one or more of the following conditions are true:
- The connection type is set to coordinated
- Multiple contexts are enabled
- You use multiple Language Environment® threads
If you attempt to allocate multiple connection handles when none of these conditions are true, the Db2 ODBC driver will return SQLSTATE 08001.
Db2 ODBC 3.0 driver applications can also use the same environment handle, connection handle, or statement handle on multiple threads. Db2 ODBC provides threadsafe access for all handles and function calls. Each connection within a single Language Environment thread maintains its own unit of recovery.

For applications that use more than one Language Environment thread, you must coordinate units of recovery and manage Db2 ODBC resources among Language Environment threads. Your application might behave unpredictably if your application does not perform this task. For example, if you call ODBC functions on different threads for the same connection simultaneously, the order in which these functions are executed at the database is unpredictable.

Attention: If you call SQLAllocHandle()with *OutputHandlePtr set to a connection or statement handle that you previously allocated, Db2 ODBC overwrites all information that is associated with that handle. Db2 ODBC does not check whether the handle that is entered in *OutputHandlePtr is in use, nor does Db2 ODBC check the previous contents of a handle before it overwrites the contents of that handle.

Return codes

After you call SQLAllocHandle(), it returns one of the following values:

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR

Diagnostics

The way that you retrieve diagnostic information from SQLAllocHandle() depends on what type of handle you allocate. To retrieve diagnostic information from SQLAllocHandle(), you need to consider the following types of errors when you attempt to allocate a handle:

Environment handle allocation errors: When you receive an error while allocating an environment handle, the value to which the OutputHandlePtr argument points determines if you can use SQLGetDiagRec() to retrieve diagnostic information. One of the following cases occurs when you fail to allocate an environment handle:

The OutputHandlePtr argument points to SQL_NULL_HENV when SQLAllocHandle() returns SQL_ERROR. In this case, you cannot call SQLGetDiagRec() to retrieve information about this error. Because no handle is associated with the error, you cannot retrieve information about that error.
The OutputHandlePtr argument points to a value other than SQL_NULL_HENV when SQLAllocHandle() returns SQL_ERROR. In this case, the value to which the OutputHandlePtr argument points becomes a restricted environment handle. You can use a handle in this restricted state only to call SQLGetDiagRec() to obtain more error information or to call SQLFreeHandle() to free the restricted handle.

Connection or statement handle allocation errors: When you allocate a connection or statement handle, you can retrieve the following types of information:

When SQLAllocHandle() returns SQL_ERROR, it sets OutputHandlePtr to SQL_NULL_HDBC for connection handles or SQL_NULL_HSTMT for statement handles (unless the output argument is a null pointer). Call SQLGetDiagRec() on the environment handle to obtain information about a failed connection handle allocation. Call SQLGetDiagRec() on a connection handle to obtain information about a failed statement handle allocation.
When SQLAllocHandle() returns SQL_SUCCESS_WITH_INFO, it returns the allocated handle to OutputHandlePtr. To obtain additional information about the allocation, call SQLGetDiagRec() on the handle that you specified in the InputHandle argument of SQLAllocHandle().

The following table lists each SQLSTATE that this function generates with a description and explanation for each value.

Table 3. `SQLAllocHandle()` SQLSTATEs
SQLSTATE	Description	Explanation
01000	Warning.	Informational message. (`SQLAllocHandle()` returns SQL_SUCCESS_WITH_INFO for this SQLSTATE.)
08003	Connection is closed.	The HandleType argument specifies SQL_HANDLE_STMT, but the connection that is specified in the InputHandle argument is not open. The connection process must be completed successfully (and the connection must be open) for Db2 ODBC to allocate a statement handle.
08S01	Communication link failure.	The communication link between the application and data source fails before the function completes.
58004	Unexpected system failure.	This could be a failure to establish the association with the Db2 for z/OS® subsystem or any other system-related error.
HY000	General error.	An error occurred for which there was no specific SQLSTATE. The error message that `SQLGetDiagRec()` returns in the buffer that the MessageText argument describes the error and its cause.
HY001	Memory allocation failure.	Db2 ODBC is unable to allocate memory for the specified handle.
HY009	Invalid use of a null pointer.	The OutputHandlePtr argument specifies a null pointer
HY013	Unexpected memory handling error.	The HandleType argument specifies SQL_HANDLE_DBC or SQL_HANDLE_STMT, and the function call could not be processed because the underlying memory objects could not be accessed, possibly because of low-memory conditions.
HY014	No more handles.	The limit for the number of handles that can be allocated for the type of handle that is indicated by the HandleType argument has been reached.
HY092	Option type out of range.	The HandleType argument does not specify one of the following values: SQL_HANDLE_ENV SQL_HANDLE_DBC SQL_HANDLE_STMT

Restrictions

The Db2 ODBC 3.0 driver does not support multiple environments; you can allocate only one active environment at any time. If you call SQLAllocHandle() to allocate more environment handles, this function returns the original environment handle and SQL_SUCCESS. The Db2 ODBC driver keeps an internal count of these environment requests. You must call SQLFreeHandle() on the environment handle for each time that you successfully request an environment handle. The last successful SQLFreeHandle() call that you make on the environment handle frees the Db2 ODBC 3.0 driver environment. This behavior ensures that an ODBC application does not prematurely deallocate the driver environment. The Db2 ODBC 2.0 driver and Db2 ODBC 3.0 driver behave consistently in this situation.

Example

Refer to the DSN803VP sample application or DSN8O3VP in the DSN1210.SDSNSAMP data set.

SQLAllocHandle() - Allocate a handle

ODBC specifications for SQLAllocHandle()