f90SQLAllocHandle (SQLAllocHandle)

Conformance

Version Introduced: ODBC 3.0

Standards Compliance: ISO 92

Summary

f90SQLAllocHandle allocates an environment, connection, statement, or descriptor handles.

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 f90SQLAllocHandle to work with ODBC 2.x drivers, a call to f90SQLAllocHandle is mapped in the Driver Manager to SQLAllocConnect, SQLAllocEnv, or SQLAllocStmt, as appropriate.

Syntax

Arguments

HandleType [Input]

The type of handle to be allocated by f90SQLAllocHandle. Must be one of the following values:

SQL_HANDLE_ENV
SQL_HANDLE_DBC
SQL_HANDLE_STMT
SQL_HANDLE_DESC

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]

Buffer in which to return the address of the handle to the newly allocated data structure.

iRet [Output]

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_INVALID_HANDLE, or SQL_ERROR.

When allocating a handle other than an environment handle, if f90SQLAllocHandle 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.

Environment Handle Allocation Errors

Environment allocation occurs both within the Driver Manager and within each driver. The error returned by f90SQLAllocHandle with a HandleType of SQL_HANDLE_ENV depends on the level in which the error occurred.

If the Driver Manager cannot allocate memory for OutputHandle when f90SQLAllocHandle with a HandleType of SQL_HANDLE_ENV is called, f90SQLAllocHandle returns SQL_ERROR. The Driver Manager sets OutputHandle to SQL_NULL_HENV. There is no handle with which to associate additional diagnostic information. (If the driver has additional diagnostic information, it will put the information on a skeletal handle that it allocates; the Driver Manager will read the information from the diagnostic structure associated with this handle.)

The Driver Manager does not call the driver-level environment handle allocation function until the application calls f90SQLConnect, f90SQLBrowseConnect, or f90SQLDriverConnect. If an error occurs in the driver-level f90SQLAllocHandle function, then the Driver Manager - level f90SQLConnect, f90SQLBrowseConnect, or f90SQLDriverConnect function returns SQL_ERROR. The diagnostic data structure contains SQLSTATE IM004 (Driver's f90SQLAllocHandle failed), followed by a driver-specific SQLSTATE value from the driver. For example, SQLSTATE HY001 (Memory allocation error) indicates that the Driver Manager's call to the driver-level f90SQLAllocHandle returned SQL_ERROR. The error is returned on a connection handle.

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

Diagnostics

When f90SQLAllocHandle returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may be obtained by calling f90SQLGetDiagRec 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. The following table lists the SQLSTATE values commonly returned by f90SQLAllocHandle and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.

Comments

f90SQLAllocHandle is used to allocate handles for environments, connections, statements, and descriptors, as described in the following sections.

More than one environment, connection, or statement handle can be allocated by an application at a time if multiple allocations are supported by the driver. There is no limit defined in ODBC on the number of environment, connection, statement, or descriptor handles that can be allocated at any one time. Drivers may impose a limit on the number of a certain type of handle that can be allocated at a time; for more information, see the driver documentation.

If the application calls f90SQLAllocHandle with OutputHandle set to an environment, connection, statement, or descriptor handle that already exists, the driver overwrites the information associated with the handle, unless the application is using connection pooling (see "Allocating an Environment Attribute for Connection Pooling" later in this section). The Driver Manager does not check to see whether the handle entered in OutputHandle is already in use, nor does it check the previous contents of a handle before overwriting them.

Note: It is incorrect ODBC application programming to call f90SQLAllocHandle twice with the same application variable defined for OutputHandle without calling f90SQLFreeHandle to free the handle before reallocating it. Overwriting ODBC handles in such a manner may lead to inconsistent behavior or errors on the part of ODBC drivers.

f90SQLAllocHandle does not set the SQL_ATTR_ODBC_VERSION environment attribute when it is called to allocate an environment handle; the environment attribute must be set by the application, or SQLSTATE HY010 (Function sequence error) will be returned when f90SQLAllocHandle is called to allocate a connection handle.

Allocating an Environment Handle

An environment handle provides access to global information such as valid connection handles and active connection handles.

To request an environment handle, an application calls f90SQLAllocHandle with a HandleType of SQL_HANDLE_ENV and an InputHandle of SQL_NULL_HANDLE. The driver allocates memory for the environment information and passes the value of the associated handle back in the OutputHandle argument. The application passes the OutputHandle value in all subsequent calls that require an environment handle argument.

Under a Driver Manager's environment handle, if there already exists a driver's environment handle, then f90SQLAllocHandle with a HandleType of SQL_HANDLE_ENV is not called in that driver when a connection is made, only f90SQLAllocHandle with a HandleType of SQL_HANDLE_DBC. If a driver's environment handle does not exist under the Driver Manager's environment handle, then both f90SQLAllocHandle with a HandleType of SQL_HANDLE_ENV and f90SQLAllocHandle with a HandleType of SQL_HANDLE_DBC are called in the driver when the first connection handle of the environment is connected to the driver.

When the Driver Manager processes the f90SQLAllocHandle function with a HandleType of SQL_HANDLE_ENV, it checks the Trace keyword in the [ODBC] section of the system information. If it is set to 1, the Driver Manager enables tracing for the current application on a computer running Windows 95, Windows NT Server, or Windows NT Workstation. If the trace flag is set, tracing starts when the first environment handle is allocated, and ends when the last environment handle is freed.

After allocating an environment handle, an application must call f90SQLSetEnvAttr on the environment handle to set the SQL_ATTR_ODBC_VERSION environment attribute. If this attribute is not set before f90SQLAllocHandle is called to allocate a connection handle on the environment, the call to allocate the connection will return SQLSTATE HY010 (Function sequence error).

Allocating Shared Environments for Connection Pooling

Environments can be shared among multiple components on a single process. A shared environment can be used by more than one component simultaneously. When a component uses a shared environment, it can use pooled connections, which allow it to allocate and use an existing connection without re-creating that connection.

Before allocating a shared environment to be used for connection pooling, an application must first call f90SQLSetEnvAttr to set the SQL_ATTR_CONNECTION_POOLING environment attribute to SQL_CP_ONE_PER_DRIVER or SQL_CP_ONE_PER_HENV. f90SQLSetEnvAttr in this case is called with EnvironmentHandle set to null, which makes the attribute a process-level attribute.

After connection pooling has been enabled, an application then calls f90SQLAllocHandle with the HandleType argument set to SQL_HANDLE_ENV. The environment allocated by this call will be an implicit shared environment because connection pooling has been enabled. (For more information about connection pooling, see f90SQLConnect.)

When a shared environment is allocated, the environment to be used is not determined until f90SQLAllocHandle with a HandleType of SQL_HANDLE_DBC is called. At that point, the Driver Manager attempts to find an existing environment that matches the environment attributes requested by the application. If no such environment exists, one is created as a shared environment. The Driver Manager maintains a reference count for each shared environment; the count is set to 1 when the environment is first created. If a matching environment is found, the handle of that environment is returned to the application, and the reference count is incremented. An environment handle allocated this way can be used in any ODBC function that accepts an environment handle as an input argument.

Allocating a Connection Handle

A connection handle provides access to information such as the valid statement and descriptor handles on the connection and whether a transaction is currently open.

To request a connection handle, an application calls f90SQLAllocHandle with a HandleType of SQL_HANDLE_DBC. The InputHandle argument is set to the environment handle that was returned by the call to f90SQLAllocHandle that allocated that handle. The driver allocates memory for the connection information, and passes the value of the associated handle back in OutputHandle. The application passes the OutputHandle value in all subsequent calls that require a connection handle.

The Driver Manager processes the f90SQLAllocHandle function and calls the driver's f90SQLAllocHandle function when the application calls f90SQLConnect, f90SQLBrowseConnect, or f90SQLDriverConnect. (For more information, see f90SQLConnect.)

If the SQL_ATTR_ODBC_VERSION environment attribute is not set before f90SQLAllocHandle is called to allocate a connection handle on the environment, the call to allocate the connection will return SQLSTATE HY010 (Function sequence error).

When an application calls f90SQLAllocHandle with the InputHandle argument set to SQL_HANDLE_DBC, and the InputHandle argument set to a shared environment handle, the Driver Manager attempts to find an existing shared environment that matches the environment attributes set by the application. If no such environment exists, one is created, with a reference count (maintained by the Driver Manager) of 1. If a matching shared environment is found, that handle is returned to the application, and its reference count is incremented.

The actual connection to be used is not determined by the Driver Manager until f90SQLConnect or f90SQLDriverConnect is called. The Driver Manager uses the connection options in the call to f90SQLConnect (or the connection keywords in the call to f90SQLDriverConnect) and the connection attributes set after connection allocation to determine which connection in the pool should be used. For more information, see f90SQLConnect.

Allocating a Statement Handle

A statement handle provides access to statement information, such as error messages, the cursor name, and status information for SQL statement processing.

To request a statement handle, an application connects to a data source, and then calls f90SQLAllocHandle prior to submitting SQL statements. In this call, HandleType should be set to SQL_HANDLE_STMT and InputHandle should be set to the connection handle that was returned by the call to f90SQLAllocHandle that allocated that handle. The driver allocates memory for the statement information, associates the statement handle with the specified connection, and passes the value of the associated handle back in OutputHandle. The application passes the OutputHandle value in all subsequent calls that require a statement handle.

When the statement handle is allocated, the driver automatically allocates a set of four descriptors and assigns the handles for these descriptors to the SQL_ATTR_APP_ROW_DESC, SQL_ATTR_APP_PARAM_DESC, SQL_ATTR_IMP_ROW_DESC, and SQL_ATTR_IMP_PARAM_DESC statement attributes. These are called implicitly allocated descriptors. To allocate an application descriptor explicitly, see the following section, "Allocating a Descriptor Handle."

Allocating a Descriptor Handle

When an application calls f90SQLAllocHandle with a HandleType of SQL_HANDLE_DESC, the driver allocates an application descriptor. These are called explicitly allocated descriptors. The application directs a driver to use an explicitly allocated application descriptor in place of an automatically allocated one for a given statement handle by calling the f90SQLSetStmtAttr function with the SQL_ATTR_APP_ROW_DESC or SQL_ATTR_APP_PARAM_DESC Attribute. An implementation descriptor cannot be allocated explicitly, nor can an implementation descriptor be specified in an f90SQLSetStmtAttr function call.

Explicitly allocated descriptors are associated with a connection handle rather than a statement handle (as automatically allocated descriptors are). Descriptors remain allocated only when an application is actually connected to the database. Because explicitly allocated descriptors are associated with a connection handle, an application can associate an explicitly allocated descriptor with more than one statement within a connection. An implicitly allocated application descriptor, on the other hand, cannot be associated with more than one statement handle. (It cannot be associated with any statement handle other than the one that it was allocated for.) Explicitly allocated descriptor handles can be freed either explicitly by the application, by calling f90SQLFreeHandle with a HandleType of SQL_HANDLE_DESC, or implicitly when the connection is closed.

When the explicitly allocated descriptor is freed, the implicitly allocated descriptor is once again associated with the statement (the SQL_ATTR_APP_ROW_DESC or SQL_ATTR_APP_PARAM_DESC Attribute for that statement is once again set to the implicitly allocated descriptor handle). This is true for all statements that were associated with the explicitly allocated descriptor on the connection.

Code Example

See f90SQLBrowseConnect, f90SQLConnect, and f90SQLSetCursorName.

Related Subroutines