Purpose
| Specification: | DB2 CLI 5.0 | ODBC 3.0 | ISO CLI |
SQLAllocHandle() allocates environment, connection, statement, or descriptor handles.
| Note: | 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
Table 13. 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 or SQL_HANDLE_DESC, 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, statement, and descriptor handles, as described below.
Multiple environment, connection, or statement handles can be allocated by an application at a time.
If the application calls SQLAllocHandle() with *OutputHandlePtr set to an environment, connection, statement, or descriptor handle that already exists, DB2 CLI overwrites the information associated with the handle. DB2 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.
On operating systems that support multiple threads, applications can use the same environment, connection, statement, or descriptor handle on different threads. DB2 CLI provides thread safe access for all handles and function calls. The application itself might experience unpredictable behavior if the threads it creates do not co-ordinate their use of DB2 CLI resources. For more information refer to Writing Multi-Threaded Applications.
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 SQLAllocHandle() with a HandleType of SQL_HANDLE_ENV and a InputHandle of SQL_NULL_HANDLE. DB2 CLI allocates the environment handle, and passes the value of the associated handle back in *OutputHandlePtr argument. The application passes the *OutputHandle value in all subsequent calls that require an environment handle argument.
When DB2 CLI processes the SQLAllocHandle() function with a HandleType of SQL_HANDLE_ENV, it checks the Trace keyword in the [COMMON] section of the db2cli.ini file. If it is set to 1, DB2 CLI enables tracing for the current application. If the trace flag is set, tracing starts when the first environment handle is allocated, and ends when the last environment handle is freed. For more information, see TRACE.
After allocating an environment handle, an application should call SQLSetEnvAttr() on the environment handle to set the SQL_ATTR_ODBC_VERSION environment attribute. If the application is run as an ODBC application, and this attribute is not set before SQLAllocHandle() is called to allocate a connection handle on the environment, then the call to allocate the connection will return SQLSTATE HY010 (Function sequence error.).
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 SQLAllocHandle() with a HandleType of SQL_HANDLE_DBC. The InputHandle argument is set to the environment handle that was returned by the call to SQLAllocHandle() that allocated that handle. DB2 CLI allocates the connection handle, and passes the value of the associated handle back in *OutputHandlePtr. The application passes the *OutputHandlePtr value in all subsequent calls that require a connection handle.
If the SQL_ATTR_ODBC_VERSION environment attribute is not set before SQLAllocHandle() is called to allocate a connection handle on the environment, then the call to allocate the connection will return SQLSTATE HY010 (Function sequence error.) when the application is using the ODBC Driver Manager.
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 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. DB2 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 the statement handle is allocated, DB2 CLI 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, SQL_ATTR_IMP_PARAM_DESC statement attributes. To use explicitly allocated application descriptors instead of the automatically allocated ones, see the "Allocating a Descriptor Handle" section below.
Allocating a Descriptor Handle
When an application calls SQLAllocHandle() with a HandleType of SQL_HANDLE_DESC, DB2 CLI allocates an application descriptor explicitly. The application can use an explicitly allocated application descriptor in place of an automatically allocated one by calling the SQLSetStmtAttr() 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 a SQLSetStmtAttr() function call.
Explicitly allocated descriptors are associated with a connection handle rather than a statement handle (as automatically allocated descriptors are). Descriptors can be associated with a connection handle only when an application is actually connected to the database. Since explicitly allocated descriptors are associated with a connection handle, an application can explicitly associate an allocated descriptor with more than one statement within a connection. An automatically allocated application descriptor, on the other hand, cannot be associated with more than one statement handle. Explicitly allocated descriptor handles can either be freed explicitly by the application, by calling SQLFreeHandle() with a HandleType of SQL_HANDLE_DESC, or freed implicitly when the connection handle is freed upon disconnect.
When an explicitly allocated application descriptor is associated with a statement, the automatically allocated descriptor that is no longer used is still associated with the connection handle. When the explicitly allocated descriptor is freed, the automatically 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 automatically allocated descriptor handle). This is true for all statements that were associated with the explicitly allocated descriptor on the connection; each statement's original automatically allocated descriptor handle is again associated with that statement.
When a descriptor is first used, the initial value of its SQL_DESC_TYPE field is SQL_C_DEFAULT. DATA_PTR, INDICATOR_PTR, and OCTET_LENGTH_PTR are all initially set to null pointers. For the initial values of other fields, see SQLSetDescField - Set a Single Field of a Descriptor Record.
For more information see Using Descriptors.
Return Codes
When allocating a handle other than an environment handle, if SQLAllocHandle() returns SQL_ERROR, it will set OutputHandlePtr to SQL_NULL_HENV, 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
Diagnostics
Table 14. SQLAllocHandle SQLSTATEs
| SQLSTATE | Description | Explanation |
|---|---|---|
| 01000 | Warning. | Informational message. (Function returns SQL_SUCCESS_WITH_INFO.) |
| 08003 | Connection is closed. | The HandleType argument was SQL_HANDLE_STMT or SQL_HANDLE_DESC, but the connection specified by the InputHandle argument was not open. The connection process must be completed successfully (and the connection must be open) for DB2 CLI to allocate a statement or descriptor handle. |
| HY000 | General error. | An error occurred for which there was no specific SQLSTATE. The error message returned by SQLGetDiagRec() in the *MessageText buffer describes the error and its cause. |
| HY001 | Memory allocation failure. | DB2 CLI was unable to allocate memory for the specified handle. |
| HY010 | Function sequence error. | The HandleType argument was SQL_HANDLE_DBC, and SQLSetEnvAttr() has not been called to set the SQL_ODBC_VERSION environment attribute. |
| HY013 | Unexpected memory handling error. | The HandleType argument was SQL_HANDLE_DBC, SQL_HANDLE_STMT, or SQL_HANDLE_DESC; 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 has been reached. |
| HY092 | Option type out of range. | The HandleType argument was not:
|
| HYC00 | Driver not capable. | The HandleType argument was SQL_HANDLE_DESC but the DB2 CLI driver was Version 2 or earlier. |
Restrictions
None.
(The complete sample utilcli.c is also available here .)
/* From the CLI sample utilcli.c */
/* ... */
/* allocate an environment handle */
sqlrc = SQLAllocHandle( SQL_HANDLE_ENV, SQL_NULL_HANDLE, pHenv ) ;
if ( sqlrc != SQL_SUCCESS )
{ printf( "\n--ERROR while allocating the environment handle.\n" ) ;
printf( " sqlrc = %d\n", sqlrc);
printf( " line = %d\n", __LINE__);
printf( " file = %s\n", __FILE__);
return( 1 ) ;
}
/* ... */
/* allocate a database connection handle */
sqlrc = SQLAllocHandle( SQL_HANDLE_DBC, *pHenv, pHdbc ) ;
HANDLE_CHECK( SQL_HANDLE_ENV, *pHenv, sqlrc, pHenv, pHdbc ) ;
References