Core subroutine

Allocate memory for an environment handle.

call EDSAllocEnv(HENV_IV ) 

•HENV_IV An output integer value indicating the environment handle.

Description

The environment handle references global information such as active connection handles. When your application passes the address of a variable to EDSAllocEnv, EDS allocates memory and stores the value of the associated handle into the variable. Your application can then pass the HENV_IV value in all subsequent calls that require an environment handle.

Your application must request an environment handle before it can call any other EDS command. There can never be more than one environment handle allocated at one time, so your application should not call EDSAllocEnv when there is a current valid environment handle. If your application calls EDSAllocEnv with a valid environment handle, EDS overwrites the handle without regard to the previous contents of HENV_IV.

Return Values

EDSAllocEnv returns EDS_SUCCESS or EDS_ERROR.

If EDS returns EDS_ERROR for EDSAllocEnv, it will set HENV_IV to EDS_NULL_HENV. In this case, your application can assume that the error was a memory allocation error.

If your application subsequently calls EDSError with a null HENV_IV, EDSError returns EDS_INVALID_HANDLE.

A driver cannot return SQLSTATE values directly after the call to EDSAllocEnv, since no valid handle will exist with which to call EDSError.

See Also

EDSAllocConnect allocates a connection handle.

EDSConnect establishes a connection with a database.

EDSFreeEnv frees an environment handle.