Purpose
| Specification: | CLI 5.0 | ODBC 3.0 | ISO CLI |
SQLAllocHandle() allocates environment, connection, or statement handles.
This function is a generic function for allocating handles that replaces the deprecated Version 2 functions SQLAllocConnect(), SQLAllocEnv(), and SQLAllocStmt().
Syntax
SQLRETURN SQLAllocHandle (SQLSMALLINT HandleType,
SQLHANDLE InputHandle,
SQLHANDLE *OutputHandlePtr);
Function arguments
Tabelle 30. SQLAllocHandle arguments
| Data type | Argument | Use | Description |
|---|---|---|---|
| SQLSMALLINT | HandleType | input | The type of handle to be allocated by SQLAllocHandle().
Must be one of the following values:
|
| SQLHANDLE | InputHandle | input | Existing handle to use as a context for the new handle being 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, it must be a connection handle. |
| SQLHANDLE | OutputHandlePtr | output | Pointer to a buffer in which to return the handle to the newly allocated data structure. |
Usage
SQLAllocHandle() is used to allocate environment, connection, and statement handles, as described below.
Multiple statement handles can be allocated by an application at one time.
If the application calls SQLAllocHandle() with *OutputHandlePtr set to an environment, connection, statement, or descriptor handle that already exists, CLI overwrites the information associated with the handle. CLI does not check to see whether the handle entered in *OutputHandlePtr is already in use, nor does it check the previous contents of a handle before overwriting them.
For DB2 Everyplace, all handles except the statement handle are dummy handles and do not carry usable information.
A statement handle provides access to statement information, such as error messages, and status information for SQL statement processing. To request a statement handle, an application connects to a data source, and then calls SQLAllocHandle() 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 SQLAllocHandle() that allocated that handle. CLI allocates the statement handle, associates the statement handle with the connection specified, and passes the value of the associated handle back in *OutputHandlePtr. The application passes the *OutputHandlePtr value in all subsequent calls that require a statement handle.
When an application exits, all DB2 Everyplace resources allocated for the application are released, so handles that the application uses are no longer valid.
For DB2 Everyplace, no descriptor is associated with a statement handle with attributes that can be changed by an application.
When using DB2 Everyplace with Visual Basic and the DB2 Everyplace CLI/ODBC interface, you must explicitly call the mapped/underlying CLI functions defined in sqlcli.h. For example, calling SQLAllocHandle() fails. Calling SQLAllocHandleVer(SQL_HANDLE_STMT, hdbc, hstmt, DB2eVersion) is successful.
Return codes
When allocating a handle other than an environment handle, if SQLAllocHandle() returns SQL_ERROR, it sets OutputHandlePtr to SQL_NULL_HENV, SQL_NULL_HDBC, or SQL_NULL_HSTMT, 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.
Diagnostics
Tabelle 31. SQLAllocHandle SQLSTATEs
| SQLSTATE | Description | Explanation |
|---|---|---|
| 01000 | Warning. | Informational message. (Function returns SQL_SUCCESS_WITH_INFO.) |
| 08003 | Connection is closed. | The HandleType argument is SQL_HANDLE_STMT, but the connection specified by the InputHandle argument is not open. The connection process must be completed successfully (and the connection must be open) for CLI to allocate a statement handle. |
| HY000 | General error. | An error occurred for which there is no specific SQLSTATE. The error message returned by SQLGetDiagRec() in the *MessageText buffer describes the error and its cause. |
| HY001 | Memory allocation error. | CLI is unable to allocate memory for the specified handle. |
| HY013 | Unexpected memory handling error. | The HandleType argument is SQL_HANDLE_DBC, or SQL_HANDLE_STMT; and the function call could not be processed because the underlying memory objects could not be accessed, possibly because of low memory conditions. |
| HY014 | No more handles. | The limit for the number of handles that can be allocated for the type of handle indicated by the HandleType argument is reached. |
| HY092 | Option type out of range. | The HandleType argument is not:
|
Zugehörige Referenzen