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 函式 |