SQLAllocHandle

Function

SQLAllocHandle allocates environment, connection, or statement handles. This function is a generic function for allocating handles that replaces the deprecated ODBC 2.x functions SQLAllocEnv, SQLAllocConnect, and SQLAllocStmt.

Prototype

1
2
3

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

Parameter

**Table 1** SQLAllocHandle parameters
Keyword	Description
HandleType	The type of handle to be allocated by SQLAllocHandle. The value must be one of the following: SQL_HANDLE_ENV (environment handle) SQL_HANDLE_DBC (connection handle) SQL_HANDLE_STMT (statement handle) SQL_HANDLE_DESC (description handle) The handle application sequence is: SQL_HANDLE_ENV > SQL_HANDLE_DBC > SQL_HANDLE_STMT. The handle applied later depends on the handle applied prior to it.
InputHandle	Existing handle to use as a context for the new handle being allocated. If HandleType is SQL_HANDLE_ENV, this is SQL_NULL_HANDLE. If HandleType is SQL_HANDLE_DBC, this must be an environment handle. If HandleType is SQL_HANDLE_STMT or SQL_HANDLE_DESC, it must be a connection handle.
OutputHandlePtr	Output parameter: Pointer to a buffer in which to return the handle to the newly allocated data structure.

Return Values

SQL_SUCCESS indicates that the call succeeded.
SQL_SUCCESS_WITH_INFO indicates some warning information is displayed.
SQL_ERROR indicates major errors, such as memory allocation and connection failures.
SQL_INVALID_HANDLE indicates that invalid handles were called. Values returned by other APIs are similar to the preceding values.

Precautions

When allocating a non-environment handle, if SQLAllocHandle returns SQL_ERROR, it sets OutputHandlePtr to SQL_NULL_HENV, SQL_NULL_HDBC, SQL_NULL_HSTMT, or SQL_NULL_HDESC. The application can then call SQLGetDiagRec, with HandleType and Handle set to IntputHandle, to obtain the SQLSTATE value. The SQLSTATE value provides the detailed function calling information.