SQLAllocHandle

Note This function is a generic function for allocating handles that replaces the ODBC 2.0 functions SQLAllocConnect, SQLAllocEnv, and SQLAllocStmt. To allow applications calling SQLAllocHandle to work with ODBC 2.x drivers, a call to SQLAllocHandle is mapped in the Driver Manager to SQLAllocConnect, SQLAllocEnv, or SQLAllocStmt, as appropriate.

SQLRETURN SQLAllocHandle(

SQLSMALLINT HandleType,

SQLHANDLE InputHandle,

SQLHANDLE *OutputHandle

);

FUNCTION SQLAllocHandle ( _

BYVAL HandleType AS INTEGER, _

BYVAL InputHandle AS DWORD, _

BYREF OutputHandle AS DWORD _

) AS DWORD

HandleType

[Input] The type of handle to be allocated by SQLAllocHandle. Must be one of the following values:

SQL_HANDLE_ENV

SQL_HANDLE_DBC

SQL_HANDLE_DESC

SQL_HANDLE_STMT

InputHandle

[Input] The input handle in whose context the new handle is to be allocated. If HandleType is SQL_HANDLE_ENV, this is SQL_NULL_HANDLE. If HandleType is SQL_HANDLE_DBC, this must be an environment handle, and if it is SQL_HANDLE_STMT or SQL_HANDLE_DESC, it must be a connection handle.

OutputHandle

[Output] Pointer to a DWORD variable in which to return the handle to the newly allocated data structure.

When allocating a handle other than an environment handle, if SQLAllocHandle returns SQL_ERROR, it sets OutputHandle to SQL_NULL_HDBC, SQL_NULL_HSTMT, or SQL_NULL_HDESC, depending on the value of HandleType, unless the output argument is a null pointer. The application can then obtain additional information from the diagnostic data structure associated with the handle in the InputHandle argument.

When SQLAllocHandle returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value can be obtained by calling SQLGetDiagRec with the appropriate HandleType and Handle set to the value of InputHandle. SQL_SUCCESS_WITH_INFO (but not SQL_ERROR) can be returned for the OutputHandle argument.