SQLAllocEnv allocates memory for an environment handle and initializes the driver call level interface for application use. An application must call SQLAllocEnv before it calls any other driver function.
A driver cannot return SQLSTATE values directly after the call to SQLAllocEnv because no valid handle exists with which to call SQLError.
Two levels of SQLAllocEnv functions exist, one within the driver manager (if you are using one) and one within the driver. The driver manager does not call the driver-level function until the application calls SQLConnect, SQLBrowseConnect, or SQLDriverConnect. If an error occurs in the driver-level SQLAllocEnv function, the driver manager-level SQLConnect, SQLBrowseConnect, or SQLDriverConnect function returns SQL_ERROR. A subsequent call to SQLError with henv, SQL_NULL_HDBC, and SQL_NULL_HSTMT returns SQLSTATE IM004 (the driver SQLAllocEnv function failed), followed by one of the following errors from the driver:
For example, SQLSTATE S1001 (Memory-allocation failure) indicates that the call from the driver manager to the driver-level SQLAllocEnv returned SQL_ERROR, and the henv from the driver manager was set to SQL_NULL_HENV.