用途

SQLAllocStmt() 分配新的語句句柄并將其與連接句柄指定的連接相關(guān)聯(lián)。對于在任何一個時候可以分配的語句句柄數(shù)目沒有已定義的限制。

在調(diào)用此函數(shù)之前，必須調(diào)用 SQLConnect()。

必須在 SQLBindParam()、SQLPrepare()、SQLExecute()、SQLExecDirect() 或任何其它將語句句柄作為其中一個輸入自變量的函數(shù)之前調(diào)用此函數(shù)。

語法

SQLRETURN SQLAllocStmt (SQLHDBC    hdbc,
SQLHSTMT   *phstmt);

函數(shù)自變量

表 12. SQLAllocStmt 自變量

數(shù)據(jù)類型	自變量	使用	描述
SQLHDBC	hdbc	輸入	連接句柄
SQLHSTMT *	phstmt	輸出	指向語句句柄的指針

用法

DB2 UDB CLI 使用每個語句句柄來使所有描述符、結(jié)果值、游標(biāo)信息和狀態(tài)信息與已處理的 SQL 語句相關(guān)聯(lián)。雖然每個 SQL 語句都必須要有語句句柄，但可以將句柄重新用于不同的語句。

對此函數(shù)的調(diào)用要求 hdbc 引用活動的數(shù)據(jù)庫連接。

要執(zhí)行定位型更新或刪除，應(yīng)用程序必須將不同的語句句柄用于 SELECT 語句和 UPDATE 或 DELETE 語句。

如果指向語句句柄的輸入指針（phstmt）指向由先前的 SQLAllocStmt() 調(diào)用分配的有效語句句柄，則此調(diào)用的結(jié)果是覆蓋原始值。這是應(yīng)用程序編程錯誤，DB2 UDB CLI 不檢測此錯誤。

返回碼

• SQL_SUCCESS
• SQL_ERROR
• SQL_INVALID_HANDLE

如果返回 SQL_ERROR，則 phstmt 自變量設(shè)置為 SQL_NULL_HSTMT。應(yīng)用程序應(yīng)使用同一個 hdbc 來調(diào)用 SQLError() 并將 hstmt 自變量設(shè)置為 SQL_NULL_HSTMT。

診斷

表 13. SQLAllocStmt SQLSTATE

SQLSTATE	描述	說明
08003	連接未打開	hdbc 自變量指定的連接尚未打開。必須成功地為驅(qū)動程序建立連接（并且該連接必須已打開）才能分配 hstmt。
40003 *	未知語句是否完成	在函數(shù)完成處理之前，CLI 與數(shù)據(jù)源之間的通信鏈路發(fā)生故障。
58004	系統(tǒng)錯誤	不可恢復(fù)的系統(tǒng)錯誤。
HY001	內(nèi)存分配失敗	驅(qū)動程序無法分配支持此函數(shù)的執(zhí)行或完成所必需的內(nèi)存。
HY009	自變量值無效	phstmt 是空指針
HY013 *	內(nèi)存管理問題	驅(qū)動程序無法訪問支持此函數(shù)的執(zhí)行或完成所必需的內(nèi)存。

示例

請參考 SQLFetch()（示例）。