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()（示例）。