SQLAllocHandle －分配句柄

用途

规范：

DB2 CLI 5.0

ODBC 3.0

ISO CLI

SQLAllocHandle() 分配环境、连接或语句句柄。

此函数是分配句柄的类属函数，它替换废弃的版本 2 函数 SQLAllocConnect()、SQLAllocEnv() 和 SQLAllocStmt()。

语法

SQLRETURN   SQLAllocHandle   (SQLSMALLINT       HandleType,
                              SQLHANDLE         InputHandle,
                              SQLHANDLE         *OutputHandlePtr);

函数自变量

表 30. SQLAllocHandle 自变量

数据类型	自变量	使用	描述
SQLSMALLINT	`HandleType`	输入	将由 `SQLAllocHandle()` 分配的句柄类型。必须是下列其中一值： SQL_HANDLE_ENV SQL_HANDLE_DBC SQL_HANDLE_STMT
SQLHANDLE	`InputHandle`	输入	将用作所分配新句柄的上下文的现有句柄。如果 `HandleType` 是 SQL_HANDLE_ENV，则此项为 SQL_NULL_HANDLE。如果 `HandleType` 是 SQL_HANDLE_DBC，则此项必须为环境句柄；而如果 `HandleType` 是 SQL_HANDLE_STMT，则此项必须为连接句柄。
SQLHANDLE	`OutputHandlePtr`	输出	指向缓冲区的指针，在该缓冲区中，将句柄返回至新分配的数据结构。

用法

SQLAllocHandle() 用来分配环境、连接和语句句柄，如下所述。

应用程序一次可分配多个语句句柄。

如果应用程序调用 SQLAllocHandle()，且 *OutputHandlePtr 设置为已存在的环境、连接、语句或描述符句柄，则 DB2 CLI 将覆盖与该句柄相关联的信息。DB2 CLI 并不检查在 *OutputHandlePtr 中输入的句柄是否已在使用中，也不在覆盖句柄的先前内容之前检查它们。

对于 DB2 Everyplace，除语句句柄外的所有句柄都是哑句柄，并不包含可用的信息。

语句句柄提供对语句信息（如错误消息和 SQL 语句处理的状态信息）的访问。要请求语句句柄，应用程序连接数据源，然后在提交 SQL 语句之前调用 SQLAllocHandle()。在此调用中，应将 HandleType 设置为 SQL_HANDLE_STMT，并将 InputHandle 设置为调用分配该句柄的 SQLAllocHandle() 返回的连接句柄。DB2 CLI 分配语句句柄，将语句句柄与指定的连接相关联，并将相关联句柄的值传送回到 *OutputHandlePtr 中。在需要语句句柄的所有后续调用中，应用程序都传送 *OutputHandlePtr 值。

当应用程序退出时，将释放为该应用程序分配的所有 DB2 Everyplace 资源，因此该应用程序使用的句柄不再有效。

对于 DB2 Everyplace，没有任何描述符与具有应用程序可以更改的属性的语句句柄相关联。

在将 DB2 Everyplace 与 Visual Basic 和 DB2 Everyplace CLI/ODBC 接口配合使用时，必须显式调用在 sqlcli.h 中定义的映射／底层 CLI 函数。例如，调用 SQLAllocHandle() 会失败。调用 SQLAllocHandleVer(SQL_HANDLE_STMT, hdbc, hstmt, DB2eVersion) 会成功。

返回码

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR

当分配的句柄不是环境句柄时，如果 SQLAllocHandle() 返回 SQL_ERROR，则它根据 HandleType 的值将 OutputHandlePtr 设置为 SQL_NULL_HENV、SQL_NULL_HDBC 或 SQL_NULL_HSTMT（除非输出自变量为空指针）。然后，应用程序可从与 InputHandle 自变量中的句柄相关联的诊断数据结构中获取附加信息。

诊断

表 31. SQLAllocHandle SQLSTATE

SQLSTATE	描述	解释
01000	警告。	参考消息。（函数返回 SQL_SUCCESS_WITH_INFO。）
08003	连接已关闭。	`HandleType` 自变量是 SQL_HANDLE_STMT，但由 `InputHandle` 自变量指定的连接未打开。连接过程必须成功完成（且连接必须是打开的），DB2 CLI 才能分配语句句柄。
HY000	一般错误。	出错，该错误没有特定的 SQLSTATE。`*MessageText` 缓冲区中由 `SQLGetDiagRec()` 返回的错误消息描述该错误及其原因。
HY001	内存分配出错。	DB2 CLI 无法为指定的句柄分配内存。
HY013	发生意外的内存处理错误。	`HandleType` 自变量是 SQL_HANDLE_DBC 或 SQL_HANDLE_STMT；因为未能访问底层内存对象（可能是因为内存不足），所以未能处理函数调用。
HY014	不再有句柄。	已达到可对 `HandleType` 自变量所指示的句柄类型分配的句柄数限制。
HY092	选项类型超出范围。	`HandleType` 自变量不是： SQL_HANDLE_ENV SQL_HANDLE_DBC SQL_HANDLE_STMT

相关参考

SQLAllocHandle － 分配句柄

SQLAllocHandle －分配句柄