SQLCancelHandle 函式
一致性
引進的版本：ODBC 3.8 標準合規性：無
預期大部分的 ODBC 3.8（及更新版本）驅動程式都會實作此函式。 如果驅動程式未執行，在 Handle 參數中使用 連接控制碼呼叫 SQLCancelHandle 將會傳回SQL_ERROR具有 IM001 的 SQLSTATE，且訊息 「驅動程式不支援此函式」''使用語句控制碼對 SQLCancelHandle 的呼叫 ，因為 Handle 參數會對應至 Driver Manager 對 SQLCancel 的呼叫 ，而且如果驅動程式實作 SQLCancel ，則可以處理。 應用程式可以使用 SQLGetFunctions 來判斷驅動程式是否支援 SQLCancelHandle 。
摘要
SQLCancelHandle 會取消連接或語句上的處理。 驅動程式管理員會將 SQLCancelHandle 的呼叫 對應至在 HandleType SQL_HANDLE_STMT時 呼叫 SQLCancel 。
語法
SQLRETURN SQLCancelHandle(
SQLSMALLINT HandleType,
SQLHANDLE Handle);
引數
HandleType
[輸入]要進行 cacel 處理之控制碼的類型。 有效值為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時，可以使用SQL_HANDLE_STMT的 HandleType 呼叫 SQLGetDiagRec ，以及語句句 柄句 柄或 SQL_HANDLE_DBC的 HandleType 和連接控制碼控制碼 來取得 相關聯的 SQLSTATE 值。
下表列出 SQLCancelHandle 通常傳 回的 SQLSTATE 值，並說明此函式內容中的每個值;標記法 「（DM）」 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。
| SQLSTATE | 錯誤 | 描述 |
|---|---|---|
| 01000 | 一般警告 | 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| HY000 | 一般錯誤 | 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 引數 *MessageText 緩衝區中 SQLGetDiagRec 傳 回的錯誤訊息會描述錯誤及其原因。 |
| HY001 | 記憶體配置錯誤 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY010 | 函式順序錯誤 | 已針對與 Handle 相關聯的 其中一個語句控制碼呼叫非同步執行的語句相關函式，而 HandleType 已設定為SQL_HANDLE_DBC。 呼叫 SQLCancelHandle 時 ，非同步函式仍在執行中。 （DM） HandleType 引數已SQL_HANDLE_STMT;在相關聯的連接控制碼上呼叫非同步執行函式;而且呼叫此函式時仍會執行函式。 （DM） 已針對與 Handle 和 HandleType 相關聯的 其中一個語句控制碼呼叫 SQLExecute 、 SQLExecDirect 或 SQLMoreResults ，並傳回 SQL_HANDLE_DBC SQL_PARAM_DATA_AVAILABLE。 在擷取所有資料流程參數的資料之前，會呼叫此函式。 已針對 ConnectionHandle 呼叫 SQLBrowseConnect ，並傳回SQL_NEED_DATA。 此函式是在流覽程式完成之前呼叫的。 |
| HY013 | 記憶體管理錯誤 | 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。 |
| HY092 | 不正確屬性/選項識別碼 | HandleType 已設定為 SQL_HANDLE_ENV 或 SQL_HANDLE_DESC。 |
| HY117 | 連線因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 | （DM） 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式 。 |
| HYT01 | 已超過連線逾時 | 在資料來源回應要求之前，連線逾時期限已過期。 連線逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驅動程式不支援此函式 | （DM） 與 Handle 相關聯的驅動程式不支援 函式。 |
如果 呼叫 SQLCancelHandle 且 HandleType 設定為 SQL_HANDLE_STMT，它可以傳回 SQLCancel 函式可傳 回的任何 SQLSTATE。
註解
此函式類似于 SQLCancel ，但可能會採用連接或語句控制碼做為參數，而不只是語句控制碼。 驅動程式管理員會將 SQLCancelHandle 的呼叫 對應至在 HandleType SQL_HANDLE_STMT時 呼叫 SQLCancel 。 這可讓應用程式使用 SQLCancelHandle 取消語句作業，即使驅動程式未實 作 SQLCancelHandle 也一樣。
如需取消語句作業的詳細資訊，請參閱 SQLCancel 函式 。
如果處理 對 SQLCancelHandle 的 呼叫沒有進行 中的作業，則沒有任何作用。
連接控制碼上的 SQLCancelHandle 可以取消下列類型的處理：
在連接上以非同步方式執行的函式。
在另一個執行緒的連接控制碼上執行的函式。
呼叫 SQLCancelHandle 以取消在連線中以非同步方式執行的函式時 ，SQLCancelHandle 所 張貼的診斷記錄會附加至取消作業所傳回的診斷記錄： 不過，當取消在另一個執行緒上的連接上執行的函式時，SQLCancelHandle 不會傳回診斷記錄。
使用 SQLCancelHandle 取消 SQLEndTran 可能會使連線處於暫停狀態。 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式 。
注意
如需如何在將在 Windows 7 之前的 Windows 作業系統上部署之應用程式中使用 SQLCancelHandle 的詳細資訊，請參閱 相容性矩陣 。
取消連線相關的非同步處理
如果函式傳回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 來取消函式時 執行函式，則函式可能會成功並傳回SQL_SUCCESS，然後取消才會生效。 如果 SQLCancelHandle 之前 完成的作業能夠取消作業，則對 SQLCancelHandle 的呼叫 沒有任何作用。
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 取消以非同步方式在語句控制碼上執行的函式、取消需要資料的語句上的函式，或取消在另一個執行緒上語句上執行的函式。 | SQLCancel 函式 |