SQLPrepare 函式

  • 發行項

一致性
引進版本：ODBC 1.0 標準合規性：ISO 92

摘要
SQLPrepare 會準備要執行的 SQL 字串。

語法

  
SQLRETURN SQLPrepare(  
     SQLHSTMT      StatementHandle,  
     SQLCHAR *     StatementText,  
     SQLINTEGER    TextLength);

引數

StatementHandle
[輸入]語句控制碼。

StatementText
[輸入]SQL 文字字串。

TextLength
[輸入]字元中的 * StatementText 長度。

傳回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。

診斷

當 SQLPrepare 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，藉由呼叫 SQLGetDiagRec 搭配 SQL_HANDLE_STMT 的 HandleType 和 StatementHandle 句 柄 ，即可取得相關聯的 SQLSTATE 值。 下表列出 SQLPrepare 通常傳 回的 SQLSTATE 值，並說明此函式內容中的每個值;標記法 「（DM）」 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。

SQLSTATE 錯誤 描述
01000 一般警告 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。）
01S02 選項值已變更 由於實作工作條件，指定的語句屬性無效，因此會暫時取代類似的值。 （ 可以呼叫 SQLGetStmtAttr 來判斷暫時替代的值為何。替代值對 StatementHandle 有效，直到資料指標關閉為止。 可以變更的語句屬性如下：SQL_ATTR_CONCURRENCY SQL_ATTR_CURSOR_TYPE SQL_ATTR_KEYSET_SIZE SQL_ATTR_MAX_LENGTH SQL_ATTR_MAX_ROWS SQL_ATTR_QUERY_TIMEOUT SQL_ATTR_SIMULATE_CURSOR

（函式會傳回SQL_SUCCESS_WITH_INFO。）
08S01 通訊連結失敗 驅動程式與驅動程式連線的資料來源之間的通訊連結在函式完成處理之前失敗。
21S01 插入值清單不符合資料行清單 *StatementText 包含 INSERT 語句，而要插入的值數目不符合衍生資料表的程度。
21S02 衍生資料表的程度不符合資料行清單 *StatementText 包含 CREATE VIEW 語句，且指定的名稱數目與查詢規格所定義的衍生資料表不同。
22018 轉換規格的字元值無效 *StatementText 包含包含常值或參數的 SQL 語句，且值與相關聯資料表資料行的資料類型不相容。
22019 不正確逸出字元 argument StatementText 包含 WHERE 子句中具有 ESCAPE 的 LIKE 述 詞，而 ESCAPE 後面的 逸 出字元長度不等於 1。
22025 不正確逸出序列 argument StatementText 包含 WHERE 子句中的 「 LIKE 模式值 ESCAPE 逸 出字元 」，而模式值中逸出字元後面的字元既不是 「%」 或 「_」。
24000 不正確資料指標狀態 （DM） 語句上已開啟 資料指標，並 已呼叫 SQLFetch 或 SQLFetchScroll 。

語句上已開啟 資料指標，但 未呼叫 SQLFetch 或 SQLFetchScroll 。
34000 不正確資料指標名稱 *StatementText 包含定位 的 DELETE 或定位 的 UPDATE ，且所準備語句所參考的資料指標尚未開啟。
3D000 不正確目錄名稱 StatementText 中指定的 目錄名稱無效。
3F000 不正確架構名稱 StatementText 中指定的 架構名稱無效。
42000 語法錯誤或存取違規 *StatementText 包含無法預先剖析或包含語法錯誤的 SQL 語句。

*StatementText 包含使用者沒有必要許可權的語句。
42S01 基表或檢視已經存在 *StatementText 包含 CREATE TABLE 或 CREATE VIEW 語句，而且指定的資料表名稱或檢視名稱已經存在。
42S02 找不到基表或檢視表 *StatementText 包含 DROP TABLE 或 DROP VIEW 語句，且指定的資料表名稱或檢視名稱不存在。

*StatementText 包含 ALTER TABLE 語句，且指定的資料表名稱不存在。

*StatementText 包含 CREATE VIEW 語句，且查詢規格所定義的資料表名稱或檢視名稱不存在。

*StatementText 包含 CREATE INDEX 語句，且指定的資料表名稱不存在。

*StatementText 包含 GRANT 或 REVOKE 語句，且指定的資料表名稱或檢視名稱不存在。

*StatementText 包含 SELECT 語句，且指定的資料表名稱或檢視名稱不存在。

*StatementText 包含 DELETE 、 INSERT 或 UPDATE 語句，且指定的資料表名稱不存在。

*StatementText 包含 CREATE TABLE 語句，而且條件約束中指定的資料表不存在（參考所建立資料表以外的資料表）。
42S11 索引已經存在 *StatementText 包含 CREATE INDEX 語句，且指定的索引名稱已經存在。
42S12 找不到索引 *StatementText 包含 DROP INDEX 語句，且指定的索引名稱不存在。
42S21 資料行已經存在 *StatementText 包含 ALTER TABLE 語句，而且 ADD 子句中指定的 資料行不是唯一的，或識別基表中的現有資料行。
42S22 找不到資料行 *StatementText 包含 CREATE INDEX 語句，且資料行清單中指定的一或多個資料行名稱不存在。

*StatementText 包含 GRANT 或 REVOKE 語句，且指定的資料行名稱不存在。

*StatementText 包含 SELECT 、DELETE 、 INSERT 或 UPDATE 語句，且指定的資料行名稱不存在。

*StatementText 包含 CREATE TABLE 語句，且條件約束中指定的資料行不存在（參考所建立資料表以外的資料表）。
HY000 一般錯誤 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 傳 回的錯誤訊息描述錯誤及其原因。
HY001 記憶體配置錯誤 驅動程式無法配置支援執行或完成函式所需的記憶體。
HY008 作業已取消 已針對 StatementHandle 啟用非同步處理。 已呼叫函式，並在完成執行之前， 在 StatementHandle 上 呼叫 SQLCancel 或 SQLCancelHandle ，然後在 StatementHandle 上 再次呼叫函式。

呼叫函式，並在完成執行之前， 從多執行緒應用程式中的不同執行緒呼叫 語句Handle 或 SQLCancelHandle 。
HY009 不正確 Null 指標使用 （DM） StatementText 是 Null 指標。
HY010 函式順序錯誤 （DM） 已針對與 StatementHandle 相關聯的連接控制碼呼叫非同步執行函式。 呼叫 SQLPrepare 函 式時 ，這個非同步函式仍在執行中。

（DM） 已針對 StatementHandle 呼叫 SQLExecute 、 SQLExecDirect 或 SQLMoreResults ，並傳回SQL_PARAM_DATA_AVAILABLE。 在擷取所有資料流程參數的資料之前，會呼叫此函式。

（DM） 呼叫 StatementHandle 的非同步執行函式（而非此函式），並在呼叫此函式時仍在執行中。

（DM） 已針對 StatementHandle 呼叫 SQLExecute 、 SQLExecDirect 、 SQLBulkOperations 或 SQLSetPos ，並傳回SQL_NEED_DATA。 在針對所有資料執行中參數或資料行傳送資料之前，會呼叫此函式。
HY013 記憶體管理錯誤 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。
HY090 不正確字串或緩衝區長度 （DM） 引數 TextLength 小於或等於 0，但不等於SQL_NTS。
HY117 連線因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 （DM） 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式 。
HYC00 未實作選擇性功能 定義資料指標類型的並行設定無效。

SQL_ATTR_USE_BOOKMARKS語句屬性已設定為 SQL_UB_VARIABLE，且SQL_ATTR_CURSOR_TYPE語句屬性已設定為驅動程式不支援書簽的資料指標類型。
HYT00 逾時已超過 在資料來源傳回結果集之前過期的逾時期限。 逾時期間是透過 SQLSetStmtAttr 來設定，SQL_ATTR_QUERY_TIMEOUT。
HYT01 已超過連線逾時 在資料來源回應要求之前，連線逾時期限已過期。 連線逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。
IM001 驅動程式不支援此函式 （DM） 與 StatementHandle 相關聯的驅動程式不支援 函式。
IM017 在非同步通知模式中停用輪詢 每當使用通知模型時，輪詢就會停用。
IM018 尚未呼叫 SQLCompleteAsync ，以完成此控制碼上的先前非同步作業。 如果控制碼上的上一個函式呼叫傳回SQL_STILL_EXECUTING且啟用通知模式， 則必須在控制碼上呼叫 SQLCompleteAsync ，才能執行後續處理並完成作業。

註解

應用程式會呼叫 SQLPrepare ，將 SQL 語句傳送至資料來源以供準備。 如需備妥執行的詳細資訊，請參閱 準備執行 。 應用程式可以在 SQL 語句中包含一或多個參數標記。 若要包含參數標記，應用程式會將問號 （？） 內嵌至位於適當位置的 SQL 字串。 如需參數的相關資訊，請參閱 語句參數 。

注意

如果應用程式使用 SQLPrepare 來準備和 SQLExecute 來提交 COMMIT 或 ROLLBACK 語句，則 DBMS 產品之間將無法互通。 若要認可或回復交易，請呼叫 SQLEndTran 。

驅動程式可以修改 語句，以使用資料來源所使用的 SQL 形式，然後將它提交至資料來源以供準備。 特別是，驅動程式會修改用來定義特定功能的 SQL 語法的逸出序列。 （如需 SQL 語句文法的描述，請參閱 在 ODBC 和 附錄 C：SQL 文法 中逸出序列。針對驅動程式，語句控制碼類似于內嵌 SQL 程式碼中的語句識別碼。 如果資料來源支援語句識別碼，驅動程式可以將語句識別碼和參數值傳送至資料來源。

備妥語句之後，應用程式會使用 語句控制碼在稍後的函式呼叫中參考 語句。 與語句控制碼相關聯的備妥語句可以藉由呼叫 SQLExecute 來重新執行，直到應用程式使用 SQL_DROP 選項呼叫 SQLFreeStmt ，或直到語句控制碼用於 SQLPrepare 、SQLExecDirect 或其中一個目錄函式 （ SQLColumns 、 SQLTables 等等） 的呼叫 為止。 一旦應用程式準備 語句，就可以要求結果集格式的相關資訊。 對於某些實作，在 SQLPrepare 之後呼叫 SQLDescribeCol 或 SQLDescribeParam 可能不像在 SQLExecute 或 SQLExecDirect 之後 呼叫函式那麼有 效率。

當應用程式呼叫 SQLPrepare 時，某些驅動程式無法傳回語法錯誤或存取違規。 驅動程式可以處理語法錯誤和存取違規、僅限語法錯誤，或語法錯誤或存取違規。 因此，當呼叫 SQLNumResultCols 、SQLDescribeCol 、 SQLColAttribute 和 SQLExecute 等 後續相關函式時，應用程式必須能夠處理這些條件。

視驅動程式和資料來源的功能而定，在備妥語句時，可能會檢查參數資訊（例如資料類型）（如果已系結所有參數），或執行時（如果尚未系結所有參數）。 為了達到最大互通性，應用程式應該先解除系結套用至舊 SQL 語句的所有參數，再準備相同語句上的新 SQL 語句。 這可防止因為將舊參數資訊套用至新語句所造成的錯誤。

重要

藉由明確呼叫 SQLEndTran 或以自動認可模式工作來認可交易，可能會導致資料來源刪除連接上所有語句的存取計畫。 如需詳細資訊，請參閱 SQLGetInfo 中的 SQL_CURSOR_COMMIT_BEHAVIOR和SQL_CURSOR_ROLLBACK_BEHAVIOR資訊類型，以及 資料指標和備妥語句 的交易效果。

程式碼範例

請參閱 SQLBindParameter 、 SQLPutData 和 SQLSetPos 。

如需下列資訊 請參閱
配置語句控制碼 SQLAllocHandle 函式
將緩衝區系結至結果集中的資料行 SQLBindCol 函式
將緩衝區系結至參數 SQLBindParameter 函式
取消語句處理 SQLCancel 函式
執行認可或復原作業 SQLEndTran 函式
執行 SQL 語句 SQLExecDirect 函式
執行備妥的 SQL 語句 SQLExecute 函式
傳回受 語句影響的資料列數目 SQLRowCount 函式
設定資料指標名稱 SQLSetCursorName 函式

另請參閱

ODBC API 參考
ODBC 標頭檔