16.3.1 SQLAllocHandle : Hitachi Advanced Database Application Development Guide

(1) Function

This ODBC function allocates environment, connection, statement, and descriptor handles.

(2) Format

 SQLRETURN SQLAllocHandle
 (
   SQLSMALLINT     HandleType,        /* In */
   SQLHANDLE       InputHandle,       /* In */
   SQLHANDLE     * OutputHandlePtr    /* In/Out */
 )

To Page Top

(3) Arguments

HandleType

Specifies one of the following handle types:

SQL_HANDLE_ENV: Environment handle
SQL_HANDLE_DBC: Connection handle
SQL_HANDLE_STMT: Statement handle
SQL_HANDLE_DESC: Descriptor handle

InputHandle

Specifies one of the following input handles, depending on the value of the HandleType parameter:

HandleType	Value that is set for InputHandle
`SQL_HANDLE_ENV`	`SQL_NULL_HANDLE`
`SQL_HANDLE_DBC`	Environment handle
`SQL_HANDLE_STMT`	Connection handle
`SQL_HANDLE_DESC`	Connection handle

OutputHandlePtr

Specifies a pointer to the buffer used to return the new handle that was allocated.

If the return value is SQL_SUCCESS, the value of the handle has been set. If it is SQL_ERROR, the following value is set:

HandleType	Value specified for OutputHandlePtr
`SQL_HANDLE_ENV`	`NULL`
`SQL_HANDLE_DBC`	`SQL_NULL_HDBC`
`SQL_HANDLE_STMT`	`SQL_NULL_HSTMT`
`SQL_HANDLE_DESC`	`SQL_NULL_HDESC`

To Page Top

(4) Return value

This ODBC function returns SQL_SUCCESS, SQL_ERROR, or SQL_INVALID_HANDLE.

To Page Top

(5) SQLSTATE

This ODBC function returns one of the following SQLSTATE values:

SQLSTATE	Description	Remarks	Returned
`01000`	General warning	--	N
`08003`	Connection does not exist	Connection establishment has not been completed.	Y
`HY000`	General error	--	N
`HY001`	Memory allocation error		Y
`HY009`	Invalid use of null pointer		Y
`HY010`	Function sequence error	The ODBC version has not been set prior to the acquisition of a connection handle.	Y
`HY013`	Memory management error	`HandleType` is `SQL_HANDLE_DBC`, `SQL_HANDLE_STMT`, or `SQL_HANDLE_DESC`, but the memory object cannot be accessed (memory shortage).	N
`HY014`	Limit on the number of handles exceeded	--	N
`HY092`	Invalid attribute or option identifier	An invalid value was specified for `HandleType`.	Y
`HYC00`	Optional feature not implemented	--	N
`HYT01`	Connection timeout expired		N
`IM001`	Driver does not support this function		N

Legend:

Y: This SQLSTATE might be returned by the HADB ODBC driver.

N: This SQLSTATE is not returned by the HADB ODBC driver.

--: None

To Page Top