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

另請參閱

ODBC API 參考
ODBC 標頭檔