SQLCancel 函式
一致性
引進版本：ODBC 1.0 標準合規性：ISO 92
摘要
SQLCancel 會取消語句上的處理。
若要取消連接或語句上的處理，請使用 SQLCancelHandle 函式 。
語法
SQLRETURN SQLCancel(
SQLHSTMT StatementHandle);
引數
StatementHandle
[輸入]語句控制碼。
傳回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。
診斷
當 SQLCancel 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時 ，藉由呼叫 SQLGetDiagRec 搭配 SQL_HANDLE_STMT的 HandleType 和 StatementHandle 控制碼 ，即可取得相關聯的 SQLSTATE 值。 下表列出 SQLCancel 通常傳 回的 SQLSTATE 值，並說明此函式內容中的每個值;標記法 「（DM）」 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。
| SQLSTATE | 錯誤 | 描述 |
|---|---|---|
| 01000 | 一般警告 | 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| HY000 | 一般錯誤 | 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 引數 *MessageText 緩衝區中 SQLGetDiagRec 傳 回的錯誤訊息會描述錯誤及其原因。 |
| HY001 | 記憶體配置錯誤 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY010 | 函式順序錯誤 | （DM） 已針對與 StatementHandle 相關聯的連接控制碼呼叫非同步執行函式。 呼叫 SQLCancel 函式時 ，這個非同步函式仍在執行中。 （DM） 取消作業失敗，因為與 StatementHandle 相關聯的 連接控制碼上正在進行非同步作業。 |
| HY013 | 記憶體管理錯誤 | 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。 |
| HY018 | 伺服器拒絕取消要求 | 伺服器拒絕取消要求。 |
| HY117 | 連線因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 | （DM） 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式 。 |
| HYT01 | 已超過連線逾時 | 在資料來源回應要求之前，連線逾時期限已過期。 連線逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驅動程式不支援此函式 | （DM） 與 StatementHandle 相關聯的驅動程式不支援 函式。 |
註解
SQLCancel 可以取消語句上的下列處理類型：
在 語句上以非同步方式執行的函式。
需要資料的語句函式。
在另一個執行緒的 語句上執行的函式。
在 ODBC 2 中。 x ，如果應用程式在語句上未執行任何處理時呼叫 SQLCancel， SQLCancel 的效果會與 SQLFreeStmt 搭配 SQL_CLOSE 選項相同;此行為只會定義為完整性，而且應用程式應該呼叫 SQLFreeStmt 或 SQLCloseCursor 來關閉資料指標。
當 呼叫 SQLCancel 以非同步方式取消在語句中執行的函式或需要資料的語句上的函式時，會清除所取消函式所張貼的診斷記錄，而 SQLCancel 會張貼自己的診斷記錄;當呼叫 SQLCancel 以取消在另一個執行緒的語句上執行的函式時 ，它不會清除所取消函式的診斷記錄，也不會張貼自己的診斷記錄。
取消非同步處理
應用程式以非同步方式呼叫函式之後，它會重複呼叫 函式，以判斷函式是否已完成處理。 如果函式仍在處理中，則會傳回SQL_STILL_EXECUTING。 如果函式已完成處理，則會傳回不同的程式碼。
在傳回SQL_STILL_EXECUTING的任何函式呼叫之後，應用程式可以呼叫 SQLCancel 來取消函式。 如果取消要求成功，驅動程式會傳回SQL_SUCCESS。 此訊息不代表函式實際上已取消，其表示系統已處理取消的要求。 當 或 如果函式實際取消為驅動程式相依和資料來源相依時。 應用程式必須繼續呼叫原始函式，直到傳回碼未SQL_STILL_EXECUTING為止。 如果已成功取消函式，傳回碼會SQL_ERROR且 SQLSTATE HY008（作業已取消）。 如果函式完成正常處理，如果函式成功或SQL_ERROR，且函式失敗，則傳回碼會SQL_SUCCESS或SQL_SUCCESS_WITH_INFO，以及 HY008 以外的 SQLSTATE（作業已取消）。
注意
在 ODBC 3.5 中，當語句上未執行任何處理時，不會使用 SQL_CLOSE 選項將 SQLCancel 呼叫 視為 SQLFreeStmt ，但完全沒有作用。 若要關閉資料指標，應用程式應呼叫 SQLCloseCursor 而非 SQLCancel。
如需非同步處理的詳細資訊，請參閱 非同步執行 。
取消需要資料的函式
在 SQLExecute 或 SQLExecDirect 傳回SQL_NEED_DATA，而且在針對所有資料執行參數傳送資料之前，應用程式可以呼叫 SQLCancel 來取消語句執行。 取消語句之後，應用程式可以再次呼叫 SQLExecute 或 SQLExecDirect 。 如需詳細資訊，請參閱 SQLBindParameter 。
在 SQLBulkOperations 或 SQLSetPos 傳回SQL_NEED_DATA之後，以及針對所有資料執行中資料行傳送資料之前，應用程式可以呼叫 SQLCancel 來取消作業。 取消作業之後，應用程式可以再次呼叫 SQLBulkOperations 或 SQLSetPos ;取消不會影響資料指標狀態或目前的資料指標位置。 如需詳細資訊，請參閱 SQLBulkOperations 或 SQLSetPos 。
取消在另一個執行緒上執行的函式
在多執行緒應用程式中，應用程式可以取消在另一個執行緒上執行的函式。 若要取消函式，應用程式會使用與目標函式所使用的相同語句控制碼呼叫 SQLCancel ，但在不同的執行緒上。 取消函式的方式取決於驅動程式和作業系統。 如同以非同步方式取消函式，SQLCancel 的 傳回碼只會指出驅動程式是否成功處理要求。 只能傳回SQL_SUCCESS或SQL_ERROR;不會傳回診斷資訊。 如果原始函式已取消，則會傳回SQL_ERROR和 SQLSTATE HY008（作業已取消）。
如果在另一個執行緒上呼叫 SQLCancel 來取消語句執行時 執行 SQL 語句，執行可能會成功並傳回SQL_SUCCESS同時取消。 在此情況下，驅動程式管理員會假設語句執行所開啟的資料指標會由取消關閉，因此應用程式將無法使用資料指標。
如需執行緒的詳細資訊，請參閱 多執行緒 。
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 將緩衝區系結至參數 | SQLBindParameter 函式 |
| 執行大量插入或更新作業 | SQLBulkOperations 函式 |
| 除了 SQLCancel 的功能 之外，還取消在連接控制碼上以非同步方式執行的函式。 | SQLCancelHandle 函式 |
| 執行 SQL 語句 | SQLExecDirect 函式 |
| 執行備妥的 SQL 語句 | SQLExecute 函式 |
| 釋放語句控制碼 | SQLFreeStmt |
| 取得診斷記錄的欄位或診斷標頭的欄位 | SQLGetDiagField 函式 |
| 取得診斷資料結構的多個欄位 | SQLGetDiagRec 函式 |
| 傳回要傳送資料的下一個參數 | SQLParamData 函式 |
| 在執行時間傳送參數資料 | SQLPutData 函式 |
| 將資料指標放在資料列集中、重新整理資料列集中的資料，或更新或刪除結果集中的資料 | SQLSetPos 函式 |
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應