SQLAllocHandle

Description

Allocates environment, connection, statement, or descriptor handles. This function replaces the deprecated ODBC 2.x functions SQLAllocEnv, SQLAllocConnect, and SQLAllocStmt.

Prototype

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

Parameters

**Table 1** SQLAllocHandle parameters
Keyword	Description
HandleType	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 (descriptor handle) The handle allocation sequence is: environment handle > connection handle > statement handle. A later allocated handle depends on a previously allocated handle.
InputHandle	Existing handle to use as a context for the new handle being allocated. The InputHandle parameter specifies the parent handle of the handle to be created to establish the hierarchical relationship between handles. Handles of different types have different hierarchical relationships. The InputHandle parameter is used to specify the relationship. If HandleType is SQL_HANDLE_ENV, the value is SQL_NULL_HANDLE, indicating that there is no parent handle. If HandleType is SQL_HANDLE_DBC, this must be an environment handle, indicating that the connection handle is created in this environment. If HandleType is set to SQL_HANDLE_STMT or SQL_HANDLE_DESC, this parameter value must be a connection handle.
OutputHandlePtr	Output parameter: OutputHandlePtr is a pointer that points to the SQLHANDLE type and is used to return a new handle allocated.

Return Value

SQL_SUCCESS indicates that the call succeeded.
SQL_SUCCESS_WITH_INFO indicates that 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. This value may also be returned by other APIs.

Precautions

If SQLAllocHandle returns SQL_ERROR when it is used to allocate a non-environment handle, it sets OutputHandlePtr to SQL_NULL_HDBC, SQL_NULL_HSTMT, or SQL_NULL_HDESC. The application can then call SQLGetDiagRec, with HandleType and Handle set to the value of IntputHandle, to obtain the SQLSTATE value. The SQLSTATE value provides the detailed function calling information.