SQLExecDirect 函式

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

總結
如果語句中有任何參數, SQLExecDirect 就會使用參數標記變數目前的值來執行 preparable 語句。 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 時,可以藉由呼叫 SQLGetDiagRecHandleType (SQL_HANDLE_STMT)和 StatementHandle控制碼 來取得相關聯的 SQLSTATE 值。 下表列出 SQLExecDirect 常傳回的 SQLSTATE 值,並在此函式的內容中說明每一個值;「 (DM) 」標記法優先于驅動程式管理員所傳回的 SQLSTATEs 描述。 除非另有說明,否則會 SQL_ERROR 與每個 SQLSTATE 值相關聯的傳回碼。

SQLSTATE 錯誤 描述
01000 一般警告 驅動程式特定的告知性訊息。 (函數會傳回 SQL_SUCCESS_WITH_INFO。 )
01001 資料指標操作衝突 *StatementText 包含定位的 update 或 delete 語句,而且沒有任何資料列或多個資料列已更新或刪除。 (如需多個資料列更新的詳細資訊,請參閱 SQLSetStmtAttr 中 SQL_ATTR_SIMULATE_CURSOR 屬性 的描述。 )

(函數會傳回 SQL_SUCCESS_WITH_INFO。 )
01003 Set 函式中已刪除 Null 值 引數 StatementText 包含 set 函數 (例如 AVGMAXMIN 等等) ,而不是 COUNT set 函數,而且在套用函式之前,會刪除 Null 引數值。 (函數會傳回 SQL_SUCCESS_WITH_INFO。 )
01004 字串資料,右邊已截斷 針對輸入/輸出或輸出參數傳回的字串或二進位資料,導致截斷非空白字元或非 Null 的二進位資料。 如果是字串值,就會以正確的方式截斷。 (函數會傳回 SQL_SUCCESS_WITH_INFO。 )
01006 許可權未撤銷 *StatementText 包含 REVOKE 語句,且使用者沒有指定的許可權。 (函數會傳回 SQL_SUCCESS_WITH_INFO。 )
01007 未授與許可權 * StatementTextGRANT 語句,無法授與使用者指定的許可權。
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 引數所識別的資料值,無法轉換為 SQLBindParameterParameterType 引數所識別的資料類型。

針對系結為 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 語句的資料 行識別碼 引數中,針對 VIEW 所指定的資料行數目) 包含的名稱比 SQL 語句的 查詢規格 引數所定義的衍生資料表中的資料行數目多。
22001 字串資料,右截斷 將字元或二進位值指派給資料行時,會截斷非空白字元資料或非 null 的二進位資料。
22002 需要指標變數,但未提供 Null 資料系結至輸出參數,其 StrLen_or_IndPtrSQLBindParameter 設定為 null 指標。
22003 數值超出範圍 *StatementText 包含包含系結數值參數或常值的 SQL 語句,而此值會造成整個 (,而不是在指派給相關聯的資料表資料行時,要截斷之數位的小數) 部分。

將數值或字串) 傳回 (為一個或多個輸入/輸出或輸出參數的數值或字串,將會導致整個 (與要截斷之數位) 部分的分數相反。
22007 不正確日期時間格式 *StatementText 包含包含日期、時間或時間戳記結構作為系結參數的 SQL 語句,而參數分別是不正確日期、時間或時間戳記。

輸入/輸出或輸出參數已系結至日期、時間或時間戳記 C 結構,而傳回參數中的值分別是不正確日期、時間或時間戳記。 (函數會傳回 SQL_SUCCESS_WITH_INFO。 )
22008 日期時間欄位溢位 *StatementText 包含包含 datetime 運算式的 SQL 語句,在計算時,會產生不正確日期、時間或時間戳記結構。

針對輸入/輸出或輸出參數計算的日期時程表達式會產生不正確日期、時間或時間戳記 C 結構。
22012 零除 *StatementText 包含的 SQL 語句,包含導致零除的算術運算式。

針對輸入/輸出或輸出參數計算的算術運算式會導致除數為零。
22015 間隔欄位溢位 * StatementText 包含精確的數值或間隔參數,當轉換成間隔 SQL 資料類型時,會造成有效位數遺失。

* StatementText 包含一個間隔參數,其中包含一個以上的欄位,當轉換成資料行中的數值資料類型時,不會在數值資料類型中表示。

* StatementText 包含指派給間隔 SQL 類型的參數資料,而且間隔 SQL 類型中沒有 C 類型值的表示。

指派輸入/輸出或輸出參數,其為間隔 C 類型的精確數值或間隔 SQL 類型會導致遺失有效位數。

將輸入/輸出或輸出參數指派給間隔 C 結構時,間隔資料結構中不會有資料的表示。
22018 轉換規格的字元值無效 * StatementText 包含的 C 類型是精確或近似的數值、日期時間或間隔資料類型、資料行的 SQL 類型是字元資料類型,而且資料行中的值不是系結 C 類型的有效常值。

當傳回輸入/輸出或輸出參數時,SQL 類型是精確或近似的數值、日期時間或間隔資料類型;C 類型為 SQL_C_CHAR;且資料行中的值不是系結 SQL 類型的有效常值。
22019 不正確 escape 字元 *StatementText 包含包含 LIKE 述詞的 SQL 語句,在 WHERE 子句中具有 escape而 escape 字元之後的 escape 字元長度不等於1。
22025 不正確 escape 順序 *StatementText 包含 WHERE 子句中包含「類似模式值 escape escape 字元」的 SQL 語句,而模式值中的 ESCAPE 字元後面的字元不是 "%" 或 "_" 的其中一個。
23000 完整性條件約束違規 *StatementText 包含一個包含參數或常值的 SQL 語句。 在相關聯的資料表資料行中定義為 NOT Null 的資料行的參數值為 Null,則為數據行提供了重複的值,限制為只包含唯一值,或違反了某些其他的完整性條件約束。
24000 指標狀態無效 SQLFetchSQLFetchScroll 位於 StatementHandle 上的資料指標。 如果 SQLFetchSQLFetchScroll 尚未傳回 SQL_NO_DATA,驅動程式管理員會傳回此錯誤,如果 SQLFetchSQLFetchScroll 已傳回 SQL_NO_DATA,驅動程式會傳回此錯誤。

資料指標已開啟,但未放置於 StatementHandle 上。

*StatementText 包含定位的 update 或 delete 語句,且資料指標位於結果集的開頭或結果集結尾之後。
34000 指標名稱無效 *StatementText 包含定位的 update 或 delete 語句,而執行的語句所參考的資料指標並未開啟。
3D000 不正確目錄名稱 StatementText 中指定的目錄名稱無效。
3F000 不正確架構名稱 StatementText 中指定的架構名稱無效。
40001 序列化失敗 因為另一個交易發生資源鎖死,所以已回復交易。
40003 語句完成不明 在此函數執行期間,相關聯的連接失敗,而且無法判斷交易的狀態。
42000 語法錯誤或存取違規 *StatementText 包含未 preparable 或包含語法錯誤的 SQL 語句。

使用者沒有執行 *StatementText 中所含之 SQL 語句的許可權。
42S01 基表或視圖已經存在 *StatementText 包含 CREATE TABLECREATE VIEW 語句,而且指定的資料表名稱或視圖名稱已存在。
42S02 找不到基表或視圖 *StatementText 包含 Drop TABLEdrop VIEW 語句,而且指定的資料表名稱或視圖名稱不存在。

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

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

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

*StatementText 包含 GRANTREVOKE 語句,且指定的資料表名稱或視圖名稱不存在。

*StatementText 包含 SELECT 語句,而指定的資料表名稱或視圖名稱不存在。

*StatementText 包含 DELETEINSERTUPDATE 語句,但指定的資料表名稱不存在。

*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 包含 GRANTREVOKE 語句,且指定的資料行名稱不存在。

*StatementText 包含 SELECTDELETEINSERTUPDATE 語句,但指定的資料行名稱不存在。

*StatementText 包含 CREATE TABLE 語句,以及在條件約束中指定的資料行 (參考) 不存在的資料表。

*StatementText 包含 CREATE SCHEMA 語句,但指定的資料行名稱不存在。
44000 WITH CHECK OPTION 違規 引數 StatementText 包含對已查看之資料表所執行的 INSERT 語句,或是由指定 WITH CHECK OPTION 所建立之已查看資料表的資料表,因此,受 INSERT 語句影響的一或多個資料列將不會再出現在已查看的資料表中。

引數 StatementText 包含對已查看的資料表執行的 UPDATE 語句,或從透過指定 WITH CHECK OPTION 所建立之已查看資料表衍生的資料表,如此一來,受 UPDATE 語句影響的一或多個資料列就不會再出現在已查看的資料表中。
HY000 一般錯誤 發生未定義特定 SQLSTATE 的錯誤,且未定義任何執行特定的 SQLSTATE。 SQLGetDiagRec* MessageText 緩衝區中傳回的錯誤訊息會描述錯誤及其原因。
HY001 記憶體配置錯誤 驅動程式無法配置支援執行或完成函式所需的記憶體。
HY008 已取消作業 StatementHandle 已啟用非同步處理。 呼叫函式,並在完成執行之前,在 StatementHandle 上呼叫 SQLCancelSQLCancelHandle 。 然後在 StatementHandle 上再次呼叫該函式。

呼叫函式,並在完成執行之前,從多執行緒應用程式中的不同執行緒在 StatementHandle 上呼叫 SQLCancelSQLCancelHandle
HY009 Null 指標的用法無效 (DM) *StatementText 為 null 指標。
HY010 函數順序錯誤 (DM) 以非同步方式執行的函式,是與 StatementHandle 相關聯的連接控制碼所呼叫。 呼叫 SQLExecDirect 函式時,仍在執行此非同步函式。

針對 StatementHandle 呼叫 SQLExecuteSQLEXECDIRECTSQLMoreResults () DM,並傳回 SQL_PARAM_DATA_AVAILABLE。 在抓取所有資料流程參數的資料之前,會呼叫此函數。

(DM) 以非同步方式執行的函式 (不是針對 StatementHandle 呼叫這個) ,而且在呼叫此函式時仍在執行。

針對 StatementHandle 呼叫 (DM) SQLExecuteSQLExecDirectSQLBulkOperationsSQLSetPos ,並傳回 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 或 long 資料來源特定資料類型;而 SQLGetInfo 中的 SQL_NEED_LONG_DATA_LEN 資訊類型為 "Y"。
HY105 不正確參數類型 SQLBindParameter 中為引數 InputOutputType 指定的值為 SQL_PARAM_OUTPUT,且參數為輸入參數。
HY109 不正確資料指標位置 *StatementText 包含定位的 update 或 delete 語句,且資料指標在已刪除或無法提取的資料列上,由 SQLSetPosSQLFetchScroll) 定位 (。
HY117 由於未知的交易狀態,連接已暫止。 只允許中斷連接和唯讀功能。 (DM) 如需暫停狀態的詳細資訊,請參閱 SQLEndTran 函數
HYC00 未執行選用功能 驅動程式或資料來源不支援 SQL_ATTR_CONCURRENCY 和 SQL_ATTR_CURSOR_TYPE 語句屬性的目前設定組合。

SQL_ATTR_USE_BOOKMARKS 語句屬性已設定為 SQL_UB_VARIABLE,而且 SQL_ATTR_CURSOR_TYPE 語句屬性已設定為驅動程式不支援書簽的資料指標類型。
HYT00 已超過逾時的設定 查詢超時時間已在資料來源傳回結果集之前過期。 Timeout 期限是透過 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 中特定功能的 escape 序列。 如需 escape 序列的語法,請參閱 ODBC 中的 Escape 序列

應用程式可以在 SQL 語句中包含一或多個參數標記。 若要包含參數標記,應用程式會在適當位置的 SQL 語句中內嵌問號 (? ) 。 如需參數的詳細資訊,請參閱 語句參數

如果 SQL 語句是 SELECT 語句,而呼叫 SQLSetCursorName 的應用程式將資料指標與語句產生關聯,則驅動程式會使用指定的資料指標。 否則,驅動程式會產生資料指標名稱。

如果資料來源處於手動認可模式 (需要明確的交易初始) ,而且尚未起始交易,則驅動程式會在傳送 SQL 語句之前起始交易。 如需詳細資訊,請參閱 手動認可模式

如果應用程式使用 SQLExecDirect 來提交 COMMITROLLBACK 語句,則在 DBMS 產品之間將無法互通。 若要認可或回復交易,應用程式會呼叫 SQLEndTran

如果 SQLExecDirect 遇到資料執行中參數,則會傳回 SQL_NEED_DATA。 應用程式會使用 SQLParamDataSQLPutData 來傳送資料。 請參閱 SQLBindParameterSQLParamDataSQLPutData和傳送 長資料

如果 SQLExecDirect 執行搜尋的 update、insert 或 delete 語句,而此語句不會影響資料來源中的任何資料列,則對 SQLExecDirect 的呼叫會傳回 SQL_NO_DATA。

如果 SQL_ATTR_PARAMSET_SIZE 語句屬性的值大於1,且 SQL 語句至少包含一個參數標記,則 SQLExecDirect 將會針對 SQLBindParameter 的呼叫中 ParameterValuePointer 引數所指向的陣列,針對每一組參數值執行 SQL 語句一次。 如需詳細資訊,請參閱 參數值陣列

如果開啟書簽,且執行的查詢無法支援書簽,則驅動程式應該透過變更屬性值,並傳回已變更) 的 SQLSTATE 01S02 (選項值,嘗試將環境強制轉換成支援書簽的一個。 如果無法變更此屬性,驅動程式應該會傳回 SQLSTATE HY024 (不正確屬性值) 。

注意

使用連接共用時,應用程式不能執行變更資料庫或資料庫內容的 SQL 語句,例如 SQL Server 中的 USE 資料庫 語句,這會變更資料來源所使用的目錄。

程式碼範例

請參閱 SQLBindColSQLGetDataODBC 程式範例

如需下列資訊 請參閱
將緩衝區系結至結果集內的資料行 SQLBindCol 函數
取消語句處理 SQLCancel 函式
執行認可或復原操作 SQLEndTran 函數
執行備妥的 SQL 語句 SQLExecute 函式
提取多個資料列 SQLFetch 函式
提取資料區塊或滾動整個結果集 SQLFetchScroll 函數
傳回資料指標名稱 SQLGetCursorName 函數
提取部分或全部資料行 SQLGetData 函數
傳回要傳送資料的下一個參數 SQLParamData 函式
準備要執行的語句 SQLPrepare 函數
在執行時間傳送參數資料 SQLPutData 函數
設定資料指標名稱 SQLSetCursorName 函式
設定語句屬性 SQLSetStmtAttr 函數

另請參閱

ODBC API 參考
ODBC 標頭檔