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