SQLCancelHandle 函式
一致性
引進的版本：ODBC 3.8 標準合規性：無
預期大部分的 ODBC 3.8（及更新版本）驅動程式都會實作此函式。 如果驅動程式沒有， 在 Handle 參數中使用連接句柄呼叫 SQLCancelHandle，將會傳回具有 IM001 的 SQLSTATE SQL_ERROR，且訊息 「驅動程式不支援此函式」A 使用語句句柄呼叫 SQLCancelHandle，因為 Handle 參數會對應至驅動程式管理員 SQLCancel 的呼叫，而且如果驅動程式可以處理會實作 SQLCancel 。 應用程式可以使用
摘要
SQLCancelHandle 會取消連接或語句上的處理。 當 HandleType SQL_HANDLE_STMT 時，驅動程式管理員會將呼叫對應至 SQLCancelHandleSQLCancel 的呼叫。
語法
SQLRETURN SQLCancelHandle(
SQLSMALLINT HandleType,
SQLHANDLE Handle);
參數
HandleType
[輸入]要取消處理的句柄類型。 有效值為SQL_HANDLE_DBC或SQL_HANDLE_STMT。
句柄
[輸入]要取消處理的句柄。
如果 Handle 不是由 HandleType所指定類型的有效句柄，SQLCancelHandle 會傳回SQL_INVALID_HANDLE。
返回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。
診斷
SQLCancelHandle 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，可以呼叫 SQLGetDiagRec，並使用 SQL_HANDLE_STMT HandleType 和語句句柄 Handle 或 HandleType SQL_HANDLE_DBC 以及 Handle連接句柄來取得相關聯的 SQLSTATE 值。
下表列出 SQLCancelHandle
| SQLSTATE | 錯誤 | 描述 |
|---|---|---|
| 01000 | 一般警告 | 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| HY000 | 一般錯誤 | 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 SQLGetDiagRec 傳回的錯誤訊息 自變數 *MessageText 緩衝區會描述錯誤及其原因。 |
| HY001 | 記憶體配置錯誤 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY010 | 函式順序錯誤 | 已針對與 Handle相關聯的其中一個語句句柄呼叫異步執行的語句相關函式，而且 HandleType 設為 SQL_HANDLE_DBC。 呼叫 SQLCancelHandle 時，異步函式仍在執行中。 （DM） HandleType 自變數SQL_HANDLE_STMT：在相關聯的連接句柄上呼叫異步執行函式;和函式在呼叫此函式時仍在執行。 （DM） SQLExecute、SQLExecDirect或 SQLMoreResults，針對與 Handle 相關聯的其中一個語句句柄呼叫，HandleType 設定為SQL_HANDLE_DBC，並傳回SQL_PARAM_DATA_AVAILABLE。 在擷取所有數據流參數的數據之前，會呼叫此函式。 SQLBrowseConnect 已呼叫 ConnectionHandle，並傳回SQL_NEED_DATA。 此函式是在瀏覽程式完成之前呼叫的。 |
| HY013 | 記憶體管理錯誤 | 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。 |
| HY092 | 無效的屬性/選項識別碼 | HandleType 設定為 SQL_HANDLE_ENV 或 SQL_HANDLE_DESC。 |
| HY117 | 聯機因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 | （DM） 如需暫停狀態的詳細資訊，請參閱 sqlEndTran 函式 。 |
| HYT01 | 線上逾時已過期 | 在數據源回應要求之前，連線逾時期限已過期。 連線逾時期間是透過 SQLSetConnectAttr設定，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驅動程式不支援此函式 | （DM） 與 Handle 相關聯的驅動程式不支援 函式。 |
如果呼叫
評論
此函式類似於 SQLCancel，但可能會接受連接或語句句柄做為參數，而不只是語句句柄。 當 HandleType SQL_HANDLE_STMT 時，驅動程式管理員會將呼叫對應至 SQLCancelHandleSQLCancel 的呼叫。 這可讓應用程式使用
如需取消語句作業的詳細資訊，請參閱 SQLCancel 函式。
如果
連接句柄上的 SQLCancelHandle 可以取消下列類型的處理：
在連接上以異步方式執行的函式。
在另一個線程的連接句柄上執行的函式。
呼叫 SQLCancelHandle 以異步方式取消在連線中執行的函式時，SQLCancelHandle 所張貼的診斷記錄會附加至取消作業所傳回的診斷記錄：SQLCancelHandle 不會傳回診斷記錄，不過，當取消在另一個線程上的連接上執行的函式時。
使用 SQLCancelHandle 取消 SQLEndTran 可能會使連線處於暫停狀態。 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式。
注意
如需如何在將在 Windows 7 之前的 Windows 作業系統上部署的應用程式中使用 SQLCancelHandle 的相關信息，請參閱 相容性矩陣。
取消異步處理 Connection-Related
如果函式傳回SQL_STILL_EXECUTING，應用程式可以呼叫 SQLCancelHandle 來取消作業。 如果取消要求成功，SQLCancelHandle 會傳回SQL_SUCCESS。 這並不表示原始函式已取消;指出已處理取消要求。 驅動程式和數據源會判斷作業何時或何時取消。 應用程式必須繼續呼叫原始函式，直到傳回碼未SQL_STILL_EXECUTING為止。 如果原始函式已取消，傳回碼會SQL_ERROR且 SQLSTATE HY008（作業已取消）。 如果原始函式完成正常處理（未取消），如果原始函式失敗，傳回碼會SQL_SUCCESS或SQL_SUCCESS_WITH_INFO，或SQL_ERROR和 HY008 以外的 SQLSTATE（作業已取消）。
取消在另一個線程上執行的函式
在多線程應用程式中，應用程式可以取消在另一個線程上執行的作業。 若要取消作業，應用程式會使用函式所使用的句柄呼叫 SQLCancelHandle，但在不同的線程上。 驅動程式和作業系統會決定如何取消作業。 SQLCancelHandle 傳回碼會指出驅動程式是否已處理要求、傳回SQL_SUCCESS或SQL_ERROR（未傳回診斷資訊）。 如果取消對原始函式的處理，原始函式會傳回 SQL_ERROR 和 SQLSTATE HY008 （作業已取消）。
如果在另一個線程上呼叫 SQLCancelHandle
相關函式
| 如需相關信息 | 看 |
|---|---|
| 取消以異步方式在語句句柄上執行的函式、取消需要數據的語句上的函式，或取消在另一個線程上語句上執行的函式。 | SQLCancel 函式 |