SQLExecDirect 函式
一致性
引進版本：ODBC 1.0 標準合規性：ISO 92
摘要
如果語句中有任何參數存在，SQLExecDirect 會使用參數標記變數的目前值來執行可預先剖析的語句。 SQLExecDirect 是提交 SQL 語句以進行一次性執行最快的方式。
語法
SQLRETURN SQLExecDirect(
SQLHSTMT StatementHandle,
SQLCHAR * StatementText,
SQLINTEGER TextLength);
引數
StatementHandle
[輸入]語句句柄。
StatementText
[輸入]要執行的 SQL 語句。
TextLength
[輸入]字元中的 *StatementText 長度。
傳回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NEED_DATA、SQL_STILL_EXECUTING、SQL_ERROR、SQL_NO_DATA、SQL_INVALID_HANDLE或SQL_PARAM_DATA_AVAILABLE。
診斷
當 SQLExecDirect 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，可以呼叫具有 SQL_HANDLE_STMT HandleType 和 StatementHandle Handle 的 HandleType 來取得相關聯的 SQLSTATE 值。 下表列出 SQLExecDirect 通常傳回的 SQLSTATE 值，並說明此函式內容中的每個值;表示法 “（DM）” 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。
| SQLSTATE | 錯誤 | 描述 |
|---|---|---|
| 01000 | 一般警告 | 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 01001 | 數據指標作業衝突 | *StatementText 包含定位的更新或刪除語句，而且不會更新或刪除任何數據列或多個數據列。 （如需多個數據列更新的詳細資訊，請參閱SQL_ATTR_SIMULATE_CURSOR SQLSetStmtAttr 中的屬性。） （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 01003 | set 函式中排除的 NULL 值 | argument StatementText 包含集合函式（例如 AVG、 MAX、 MIN 等），但未 排除 COUNT set 函式，而且在 套用函式之前會排除 NULL 自變數值。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 01004 | 字串數據，右截斷 | 針對輸入/輸出或輸出參數傳回的字串或二進位數據，導致截斷非空白字元或非 NULL 二進位數據。 如果它是字串值，則會將其右截斷。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 01006 | 許可權未撤銷 | *StatementText 包含 REVOKE 語句，而且用戶沒有指定的許可權。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 01007 | 未授與許可權 | *StatementText 是 GRANT 語句，且無法將指定的許可權授與使用者。 |
| 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。） |
| 01S07 | 小數截斷 | 輸入/輸出或輸出參數所傳回的數據被截斷，使數值數據類型的小數部分被截斷，或是時間、時間戳或間隔數據類型的時間元件小數部分被截斷。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 07002 | COUNT 欄位不正確 | SQLBindParameter 中指定的參數數目小於 *StatementText 中所包含 SQL 語句中的參數數目。 已呼叫 SQLBindParameter 並將 ParameterValuePtr 設定為 null 指標，StrLen_or_IndPtr未設定為 SQL_NULL_DATA 或 SQL_DATA_AT_EXEC，且 InputOutputType 未設定為 SQL_PARAM_OUTPUT，因此 SQLBindParameter 中指定的參數數目大於 *StatementText 中包含的 SQL 語句中的參數數目。 |
| 07006 | 受限制的數據類型屬性違規 | 系結參數之 SQLBindParameter 中 ValueType 自變數所識別的數據值無法轉換成 SQLBindParameter 中 ParameterType 自變數所識別的數據類型。 系結為 SQL_PARAM_INPUT_OUTPUT 或 SQL_PARAM_OUTPUT 的參數所傳回的數據值無法轉換成 SQLBindParameter 中 ValueType 自變數所識別的數據類型。 （如果無法轉換一或多個數據列的數據值，但成功傳回一或多個數據列，則此函式會傳回SQL_SUCCESS_WITH_INFO。 |
| 07007 | 限制的參數值違規 | 參數類型SQL_PARAM_INPUT_OUTPUT_STREAM僅用於傳送和接收部分數據的參數。 此參數類型不允許輸入系結緩衝區。 當參數類型為SQL_PARAM_INPUT_OUTPUT，且在 SQLBindParameter 中指定的 *StrLen_or_IndPtr不等於 SQL_NULL_DATA、SQL_DEFAULT_PARAM、SQL_LEN_DATA_AT_EXEC（len） 或 SQL_DATA_AT_EXEC 時，就會發生此錯誤。 |
| 07S01 | 預設參數的使用無效 | 使用 SQLBindParameter 設定的參數值已SQL_DEFAULT_PARAM，且對應的參數沒有預設值。 |
| 08S01 | 通訊連結失敗 | 驅動程式與驅動程式連線的數據源之間的通訊連結在函式完成處理之前失敗。 |
| 21S01 | 插入值清單不符合資料列清單 | *StatementText 包含 INSERT 語句，而要插入的值數目不符合衍生數據表的程度。 |
| 21S02 | 衍生數據表的程度不符合數據列清單 | *StatementText 包含 CREATE VIEW 語句，而未限定的數據行清單（SQL 語句之數據行標識元自變數中為檢視所指定的數據行數目），包含的名稱超過 SQL 語句之查詢規格自變數所定義的衍生數據表中的數據行數目。 |
| 22001 | 字串數據，右截斷 | 將字元或二進位值指派給數據行會導致截斷非空白字元數據或非 Null 二進位數據。 |
| 22002 | 需要指標變數，但未提供 | NULL 數據系結至 sqlBindParameter 所設定StrLen_or_IndPtr為 Null 指標的輸出參數。 |
| 22003 | 超出範圍的數值 | *StatementText 包含包含係結數值參數或常值的 SQL 語句，而值會在指派給相關聯的數據表數據行時，導致數位的整個（而不是小數部分）被截斷。 傳回一或多個輸入/輸出或輸出參數的數值（作為數值或字串），會導致截斷數位的整個（而不是小數部分）。 |
| 22007 | 無效的日期時間格式 | *StatementText 包含一個 SQL 語句，其中包含日期、時間或時間戳結構做為係結參數，而參數分別是無效的日期、時間或時間戳。 輸入/輸出或輸出參數係結至日期、時間或時間戳 C 結構，而傳回參數中的值分別為無效的日期、時間或時間戳。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 22008 | 日期時間欄位溢位 | *StatementText 包含包含 datetime 表達式的 SQL 語句，當計算時，會產生無效的日期、時間或時間戳結構。 針對輸入/輸出或輸出參數計算的 datetime 運算式，導致日期、時間或時間戳 C 結構無效。 |
| 22012 | 除以零 | *StatementText 包含一個 SQL 語句，其中包含算術運算式，導致除以零。 針對輸入/輸出或輸出參數計算的算術運算式，導致除以零。 |
| 22015 | 間隔欄位溢位 | *StatementText 包含確切的數值或間隔參數，當轉換成間隔 SQL 數據類型時，會導致有效位數遺失。 *StatementText 包含一個包含多個字段的 interval 參數，當轉換成數據行中的數值數據類型時，在數值數據類型中沒有表示。 *StatementText 包含指派給間隔 SQL 類型的參數數據，而且間隔 SQL 類型中沒有 C 型別的值表示法。 將精確數值或間隔 SQL 類型的輸入/輸出或輸出參數指派給間隔 C 型別，會造成有效位數遺失。 當輸入/輸出或輸出參數指派給間隔 C 結構時，間隔數據結構中沒有任何數據表示法。 |
| 22018 | 轉換規格的字元值無效 | *StatementText 包含的 C 類型是精確或近似數值、日期時間或間隔數據類型;數據行的 SQL 類型是字元數據類型;而且數據行中的值不是系結 C 型別的有效常值。 傳回輸入/輸出或輸出參數時，SQL 類型是精確或近似的數值、日期時間或間隔數據類型;C 類型SQL_C_CHAR;和數據行中的值不是系結 SQL 類型的有效常值。 |
| 22019 | 無效的逸出字元 | *StatementText 包含包含 WHERE 子句中具有 ESCAPE 之 LIKE 述詞的 SQL 語句，而 ESCAPE 後面的逸出字元長度不等於 1。 |
| 22025 | 無效的逸出序列 | *StatementText 包含 WHERE 子句中包含 “LIKE 模式值 ESCAPE 逸出字元” 的 SQL 語句，而模式值中逸出字元後面的字元不是 “%” 或 “_”。 |
| 23000 | 完整性條件約束違規 | *StatementText 包含包含參數或常值的 SQL 語句。 針對在相關聯數據表數據行中定義為 NOT NULL 的數據行而言，參數值為 NULL，針對限制只包含唯一值的數據行提供重複值，或違反某些其他完整性條件約束。 |
| 24000 | 無效的數據指標狀態 | 數據指標位於 SQLFetch 或 SQLFetchScroll 的 StatementHandle 上。 如果 SQLFetch 或 SQLFetchScroll 尚未傳回SQL_NO_DATA，而且如果 SQLFetch 或 SQLFetchScroll 傳回SQL_NO_DATA，驅動程式就會傳回此錯誤。 游標已開啟，但未放置在 StatementHandle 上。 *StatementText 包含定位的更新或刪除語句，而游標位於結果集的開頭之前或結果集結尾之後。 |
| 34000 | 無效的數據指標名稱 | *StatementText 包含定位的更新或刪除語句，且所執行之語句所參考的數據指標尚未開啟。 |
| 3D000 | 無效的目錄名稱 | StatementText 中指定的目錄名稱無效。 |
| 3F000 | 無效的架構名稱 | StatementText 中指定的架構名稱無效。 |
| 40001 | 串行化失敗 | 交易因為與另一個交易發生資源死結而回復。 |
| 40003 | 語句完成未知 | 此函式執行期間相關聯的連接失敗，且無法判斷交易的狀態。 |
| 42000 | 語法錯誤或存取違規 | *StatementText 包含無法預先剖析或包含語法錯誤的 SQL 語句。 用戶沒有許可權執行 *StatementText 中包含的 SQL 語句。 |
| 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 語句，而且條件約束中指定的數據表不存在（參考所建立數據表以外的數據表）。 *StatementText 包含 CREATE SCHEMA 語句，且指定的數據表名稱或檢視名稱不存在。 |
| 42S11 | 索引已經存在 | *StatementText 包含 CREATE INDEX 語句，且指定的索引名稱已經存在。 *StatementText 包含 CREATE SCHEMA 語句，且指定的索引名稱已經存在。 |
| 42S12 | 找不到索引 | *StatementText 包含 DROP INDEX 語句，且指定的索引名稱不存在。 |
| 42S21 | 數據行已經存在 | *StatementText 包含 ALTER TABLE 語句，而且 ADD 子句中指定的數據行不是唯一的，或識別基表中的現有數據行。 |
| 42S22 | 找不到數據行 | *StatementText 包含 CREATE INDEX 語句，且數據行清單中指定的一或多個數據行名稱不存在。 *StatementText 包含 GRANT 或 REVOKE 語句，且指定的數據行名稱不存在。 *StatementText 包含 SELECT、DELETE、INSERT 或 UPDATE 語句，且指定的數據行名稱不存在。 *StatementText 包含 CREATE TABLE 語句，且條件約束中指定的數據行不存在（參考所建立數據表以外的數據表）。 *StatementText 包含 CREATE SCHEMA 語句，且指定的數據行名稱不存在。 |
| 44000 | WITH CHECK OPTION 違規 | argument StatementText 包含在檢視數據表上執行的 INSERT 語句，或是透過指定 WITH CHECK OPTION 所建立之檢視數據表衍生的數據表，如此一或多個受 INSERT 語句影響的數據列就不再出現在檢視數據表中。 Argument StatementText 包含對檢視數據表或衍生自檢視數據表之數據表所建立之數據表所執行的 UPDATE 語句，如此一或多個受 UPDATE 語句影響的數據列就不再出現在檢視數據表中。 |
| HY000 | 一般錯誤 | 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 傳回的錯誤訊息描述錯誤及其原因。 |
| HY001 | 記憶體配置錯誤 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY008 | 作業已取消 | 已針對 StatementHandle 啟用異步處理。 已呼叫函式，並在完成執行之前，在 StatementHandle 上呼叫 SQLCancel 或 SQLCancelHandle。 然後在 StatementHandle 上再次呼叫函式。 呼叫函式，並在完成執行之前，從多線程應用程式中的不同線程呼叫語句Handle 或 SQLCancelHandle。 |
| HY009 | 無效的 Null 指標使用 | （DM） *StatementText 是 Null 指標。 |
| HY010 | 函式順序錯誤 | （DM） 已針對與 StatementHandle 相關聯的連接句柄呼叫異步執行函式。 呼叫 SQLExecDirect 函式時，這個異步函式仍在執行中。 （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。 使用 SQLBindParameter 設定的參數值是 null 指標，而且參數長度值不是 0、SQL_NULL_DATA、SQL_DATA_AT_EXEC、SQL_DEFAULT_PARAM或小於或等於SQL_LEN_DATA_AT_EXEC_OFFSET。 使用 SQLBindParameter 設定的參數值不是 null 指標;C 數據類型SQL_C_BINARY或SQL_C_CHAR;而且參數長度值小於 0，但未SQL_NTS、SQL_NULL_DATA、SQL_DATA_AT_EXEC、SQL_DEFAULT_PARAM或小於或等於SQL_LEN_DATA_AT_EXEC_OFFSET。 SQLBindParameter 所系結的參數長度值已設定為SQL_DATA_AT_EXEC;SQL 類型是SQL_LONGVARCHAR、SQL_LONGVARBINARY或長數據源特定數據類型;而 SQLGetInfo 中SQL_NEED_LONG_DATA_LEN資訊類型為 “Y”。 |
| HY105 | 無效的參數類型 | 在 SQLBindParameter 中為自變數 InputOutputType 指定的值是SQL_PARAM_OUTPUT，而且參數是輸入參數。 |
| HY109 | 無效的數據指標位置 | *StatementText 包含定位的更新或刪除語句，而且游標位於已刪除或無法擷取的數據列上（由 SQLSetPos 或 SQLFetchScroll）。 |
| HY117 | 聯機因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 | （DM） 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式。 |
| HYC00 | 未實作選擇性功能 | 驅動程式或數據源不支援SQL_ATTR_CONCURRENCY和SQL_ATTR_CURSOR_TYPE語句屬性的目前設定組合。 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 ，才能執行後續處理並完成作業。 |
註解
應用程式會呼叫 SQLExecDirect ，將 SQL 語句傳送至數據源。 如需直接執行的詳細資訊，請參閱 直接執行。 驅動程式會修改 語句，以使用數據源所使用的 SQL 形式，然後將它提交至數據源。 特別是，驅動程式會修改用來在 SQL 中定義特定功能的逸出序列。 如需逸出序列的語法，請參閱 ODBC 中的逸出序列。
應用程式可以在 SQL 語句中包含一或多個參數標記。 若要包含參數標記，應用程式會將問號 （？） 內嵌至位於適當位置的 SQL 語句。 如需參數的相關信息，請參閱 語句參數。
如果 SQL 語句是 SELECT 語句，而且如果呼叫 SQLSetCursorName 的應用程式將數據指標與語句產生關聯，則驅動程式會使用指定的數據指標。 否則，驅動程式會產生數據指標名稱。
如果數據源處於手動認可模式（需要明確交易起始），且尚未起始交易，則驅動程式會在傳送 SQL 語句之前起始交易。 如需詳細資訊，請參閱 手動認可模式。
如果應用程式使用 SQLExecDirect 提交 COMMIT 或 ROLLBACK 語句，DBMS 產品之間將無法互通。 若要認可或回復交易，應用程式會呼叫 SQLEndTran。
如果 SQLExecDirect 遇到資料執行中參數，則會傳回SQL_NEED_DATA。 應用程式會使用 SQLParamData 和 SQLPutData 來傳送數據。 請參閱 SQLBindParameter、 SQLParamData、 SQLPutData 和 傳送長數據。
如果 SQLExecDirect 執行搜尋的更新、插入或刪除語句，而不會影響數據源的任何數據列，則對 SQLExecDirect 的呼叫會傳回SQL_NO_DATA。
如果 SQL_ATTR_PARAMSET_SIZE 語句屬性的值大於 1，且 SQL 語句包含至少一個參數標記，SQLExecDirect 會針對呼叫 SQLBindParameter 時，ParameterValuePointer 自變數指向的每個參數值集執行一次 SQL 語句。 如需詳細資訊，請參閱 參數值的陣列。
如果開啟書籤且執行不支援書籤的查詢，驅動程式應該嘗試藉由變更屬性值並傳回 SQLSTATE 01S02 （選項值已變更），將環境強制轉換為支援書籤的環境。 如果無法變更屬性，驅動程式應該會傳回 SQLSTATE HY024 （無效的屬性值）。
注意
使用連接共用時，應用程式不得執行變更資料庫或資料庫內容的 SQL 語句，例如 SQL Server 中的 USE 資料庫 語句，這會變更數據源所使用的目錄。
程式碼範例
請參閱 SQLBindCol、 SQLGetData 和 範例 ODBC 程式。
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 將緩衝區系結至結果集中的數據行 | SQLBindCol 函式 |
| 取消語句處理 | SQLCancel 函式 |
| 執行認可或復原作業 | SQLEndTran 函式 |
| 執行備妥的 SQL 語句 | SQLExecute 函式 |
| 擷取多個數據列 | SQLFetch 函式 |
| 擷取數據區塊或捲動結果集 | SQLFetchScroll 函式 |
| 傳回數據指標名稱 | SQLGetCursorName 函式 |
| 擷取部分或所有數據行的數據 | SQLGetData 函式 |
| 傳回要傳送數據的下一個參數 | SQLParamData 函式 |
| 準備語句以供執行 | SQLPrepare 函式 |
| 在運行時間傳送參數數據 | SQLPutData 函式 |
| 設定數據指標名稱 | SQLSetCursorName 函式 |
| 設定語句屬性 | SQLSetStmtAttr 函式 |