Allocating an environment handle

This is the first task any ODBC application must perform. Before a connection or any calls to the ODBC-API can be done, the application must request an environment handle from the driver manager. To allocate an environment handle, an application calls the subroutine f90SQLAllocHandle using the SQL_HANDLE_ENV option. The definition of subroutine f90SQLAllocHandle is as follows:

Argument HandleType is an integer that indicates the type of handle to be allocated. f90SQL offers predefined constants that can be used to identify the type of handle (for example, the constant SQL_HANDLE_ENV identifies a environment handle). Argument ParentHandle is a handle to the context in which the new handle will be defined. When allocating a environment handle, ParentHandle is always set to null (using 0 or the constant SQL_NULL_HANDLE). NewHandle is the integer variable that will store the new handle. Subroutine f90SQLAllocHandle will return a status code in iRet indicating whether the operation was completed successfully.

In the following example:

we request the driver to allocate the necessary space to store the ODBC environment information. The address of this space (a pointer) is returned in the variable EnvHndl. Typically, the only use an application gives to the value stored in EnvHndl is to pass it as an argument to other ODBC functions. An application can have only one allocated environment at any given time.

When the application has finished using ODBC, it frees the environment handle with f90SQLFreeHandle. After freeing the environment, it is an application programming error to use the environment’s handle in a call to an ODBC function. Doing so has undefined but probably fatal consequences.

When f90SQLFreeHandle is called, the driver releases the structure used to store information about the environment. Note that f90SQLFreeHandle cannot be called for an environment handle until all connection handles in that environment handle have been freed.