SQLAllocEnv allocates memory for an environment handle and initializes the ODBC call level interface for use by an application. An application must call SQLAllocEnv prior to calling any other ODBC function.

If SQLAllocEnv returns SQL_ERROR, it will set the henv referenced by phenv to SQL_NULL_HENV. In this case, the application can assume that the error was a memory allocation error.

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

There are two levels of SQLAllocEnv functions, one within the Driver Manager and one within each 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, then 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 (Driver's SQLAllocEnv failed), followed by one of the following errors from the driver:

• SQLSTATE S1000 (General error).

• A driver-specific SQLSTATE value, ranging from S1000 to S19ZZ. For example, SQLSTTE S1001 (Memory allocation failure) indicates that the Driver Manager's call to the driver-level SQLAllocEnv returned SQL_ERROR, and the Driver Manager's henv was set to SQL_NULL_HENV.

For additional information about the flow of function calls between the Driver Manager and a driver, see the SQLConnect function description.

An environment handle references global information such as valid connection handles and active connection handles. To request an environment handle, an application passes the address of an henv to SQLAllocEnv. The driver allocates memory for the environment information and stores the value of the associated handle in the henv. On operating systems that support multiple threads, applications can use the same henv on different threads and drivers must therefore support safe, multithreaded access to this information. The application passes the henv value in all subsequent calls that require an henv.

There should never be more than one henv allocated at one time and the application should not call SQLAllocEnv when there is a current valid henv. If the application calls SQLAllocEnv with a pointer to a valid henv, the driver overwrites the henv without regard to its previous contents. (ODBCSDK/OverDRIVER returns the same handle.)

When the Driver Manager processes the SQLAllocEnv function, it checks the Trace keyword in the [ODBC] section of the ODBC.INI file or the ODBC subjey in the registry. If it is set to 1, the Driver Manager enables tracing for all applications on Windows 3.1 or for the current application on WindowsNT.

See SQLBrowseConnect and SQLConnect.

ODBC Router

ODBC Router transparently makes all ODBC drivers on a central Windows Server useable by your network's Linux, Macintosh and Windows systems. Three years in the making, ODBC Router has saved its customers millions of dollars in DLL installation and ODBC support costs for less than the price of a new PC and a few minutes installation time. ODBC Router provides a low cost, turnkey database network with enterprise class IT support.

Ditching the ODBC Administrator Control Panel:

By linking your application with the free ODBC Router client-side SDK instead of the ODBC Driver Manager, the need for your end-users to deal with driver installation or an ODBC Control Panel is gone! We even provide a setup function your code may call to display a "network browser" that enables your customer to "find" their ODBC Router server on the network, then "choose" the exact database they want to work with and finally return to your application with a fully-formed ODBC connection-string that may be stored and passed back to SQLConnect or SQLDriverConnect anytime your user wants to initiate a connection that data source. No more walking your customers through the process of adding data sources to ODBC Control Panel or, in the case of non-Windows computers, no need to worry about whether or not a compatible third-party ODBC Driver Manager has been installed for use with your code. (Remember that ODBC Router supports Mac OS 9, Mac OS X, Linux and Windows.) If there ever are any client-side ODBC support issues, AugSoft can handle them directly with the customer freeing you to focus on the application.

ODBC or JDBC?

JDBC drivers launch a CPU-intensive virtual machine in the background on your machine, which is bad for shared servers and for battery powered laptops or entry level desktops (that typically have slow busses and drives). As the world shifted to laptops and shared servers, the whole "virtual machine" concept became a support nightmare and so these days good Java apps are compiled to run as native (not emulated) code. Java developers may use the operating system's native ODBC support from within the JDBC class library using the sun.jdbc.odbc.JdbcOdbcDriver driver with a URL as shown below.

jdbc:odbc:dsn[;key=value]*

Example:

jdbc:odbc:finance;UID=cfo;

IT techs may then complete the database connection on the Customer's machine using ODBC Router or the database vendor's official ODBC driver.

NOTE: By creating ODBC data sources with ODBC Router, your apps will enjoy native speed and database independent connections from either Java/C/C++/C#/ObjC or PHP/PERL/Python/Ruby/BASIC on Linux, Macintosh and Windows. Also be aware that using ODBC Router with the Mac platform is an especially good idea because database vendors have not kept their Mac drivers in sync with Windows and there are actual third-party vendors who wrap freeware and JDBC drivers inside of ODBC "shells" without warning their customers! This problem is of great concern to developers because fake drivers almost always fly past the IT guys who test with speed deamon desktops, but fail the enterprise when user laptops and iMacs take too long to run queries or slowly corrupt the database when they do. IT guys often chalk this up to "network problems" leaving users with poison drivers to avoid their database. ODBC Router addresses this issue by enabling official vendor supported Windows ODBC drivers (on a Windows Server) to be accessed from all platforms, network wide.

ODBC 3.x?

It's not here yet. Even in 2010, most ODBC drivers are ODBC 1.x and 2.x. The ODBC Driver Manager translates between 3.x and 2.x or 2.x and 1.x ODBC calls. Therefore, if you don't need UNICODE, it's a bad idea to use ODBC 3.x API calls. That said, UNICODE is a Good Thing and there are actually at least three databases that natively support it now, so look for 3.x to be here soon.

Need ODBC API Help?

We really know ODBC and we routinely provide code-level ODBC help to our customers. Our low cost ODBC Router systems are available now at our online store and if your site buys them, you may open a ticket to ask ODBC development questions --we offer both E-Mail and On-Call support options in seven of the G8's timezones! Be sure to test your ODBC Router and ask for any needed installation help before purchase because we aren't Fry's --no refunds please, our prices are too low for such nonsense and we're too busy supporting real Customers!