Prayer

用途

SQLAllocStmt() 分配新的语句句柄并将其与连接句柄指定的连接相关联。对于在任何一个时候可以分配的语句句柄数目没有已定义的限制。

在调用此函数之前，必须调用 SQLConnect()。

必须在 SQLBindParam()、SQLPrepare()、SQLExecute()、SQLExecDirect() 或任何其它将语句句柄作为其中一个输入自变量的函数之前调用此函数。

语法

SQLRETURN SQLAllocStmt (SQLHDBC    hdbc,
SQLHSTMT   *phstmt);

函数自变量

表 12. SQLAllocStmt 自变量

数据类型	自变量	使用	描述
SQLHDBC	hdbc	输入	连接句柄
SQLHSTMT *	phstmt	输出	指向语句句柄的指针

用法

DB2 UDB CLI 使用每个语句句柄来使所有描述符、结果值、游标信息和状态信息与已处理的 SQL 语句相关联。虽然每个 SQL 语句都必须要有语句句柄，但可以将句柄重新用于不同的语句。

对此函数的调用要求 hdbc 引用活动的数据库连接。

要执行定位型更新或删除，应用程序必须将不同的语句句柄用于 SELECT 语句和 UPDATE 或 DELETE 语句。

如果指向语句句柄的输入指针（phstmt）指向由先前的 SQLAllocStmt() 调用分配的有效语句句柄，则此调用的结果是覆盖原始值。这是应用程序编程错误，DB2 UDB CLI 不检测此错误。

返回码

• SQL_SUCCESS
• SQL_ERROR
• SQL_INVALID_HANDLE

如果返回 SQL_ERROR，则 phstmt 自变量设置为 SQL_NULL_HSTMT。应用程序应使用同一个 hdbc 来调用 SQLError() 并将 hstmt 自变量设置为 SQL_NULL_HSTMT。

诊断

表 13. SQLAllocStmt SQLSTATE

SQLSTATE	描述	说明
08003	连接未打开	hdbc 自变量指定的连接尚未打开。必须成功地为驱动程序建立连接（并且该连接必须已打开）才能分配 hstmt。
40003 *	未知语句是否完成	在函数完成处理之前，CLI 与数据源之间的通信链路发生故障。
58004	系统错误	不可恢复的系统错误。
HY001	内存分配失败	驱动程序无法分配支持此函数的执行或完成所必需的内存。
HY009	自变量值无效	phstmt 是空指针
HY013 *	内存管理问题	驱动程序无法访问支持此函数的执行或完成所必需的内存。

示例

请参考 SQLFetch()（示例）。