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¶
SQLRETURN SQLAllocHandle(SQLSMALLINT HandleType,
SQLHANDLE InputHandle,
SQLHANDLE *OutputHandlePtr);
Parameter¶
Keyword | Description |
|---|---|
HandleType | The type of handle to be allocated by SQLAllocHandle. The value must be one of the following:
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.
|
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.
Examples¶
See Examples.