Funzione SQLCancelHandle

Conformità
Versione introdotta: Conformità agli standard ODBC 3.8: Nessuno

È previsto che la maggior parte dei driver ODBC 3.8 (e versioni successive) implementi questa funzione. In caso contrario, una chiamata a SQLCancelHandle con un handle di connessione nel parametro Handle restituirà SQL_ERROR con UN VALORE SQLSTATE IM001 e il messaggio "Il driver non supporta questa funzione". Una chiamata a SQLCancelHandle con un handle di istruzione perché il parametro Handle verrà mappato a una chiamata a SQLCancel da Gestione driver e può essere elaborato se il driver implementa SQLCancel. Un'applicazione può usare SQLGetFunctions per determinare se un driver supporta SQLCancelHandle.

Summary
SQLCancelHandle annulla l'elaborazione su una connessione o un'istruzione. Gestione driver esegue il mapping di una chiamata a SQLCancelHandle a una chiamata a SQLCancel quando HandleType è SQL_HANDLE_STMT.

Sintassi

  
SQLRETURN SQLCancelHandle(  
      SQLSMALLINT  HandleType,  
      SQLHANDLE    Handle);  

Argomenti

HandleType
[Input] Tipo dell'handle su cui eseguire l'elaborazione cacel. I valori validi SQL_HANDLE_DBC o SQL_HANDLE_STMT.

Handle
[Input] Handle su cui annullare l'elaborazione.

Se Handle non è un handle valido del tipo specificato da HandleType, SQLCancelHandle restituisce SQL_INVALID_HANDLE.

Restituisce

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnostica

Quando SQLCancelHandle restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con handleType di SQL_HANDLE_STMT e handle di istruzione o HandleType di SQL_HANDLE_DBC e handle di connessione.

La tabella seguente elenca i valori SQLSTATE comunemente restituiti da SQLCancelHandle e ne illustra ognuno nel contesto di questa funzione. la notazione "(DM)" precede le descrizioni di SQLSTATE restituite da Gestione driver. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, se non specificato diversamente.

SQLSTATE Errore Descrizione
01000 Avviso generale Messaggio informativo specifico del driver. La funzione restituisce SQL_SUCCESS_WITH_INFO.
HY000 Errore generale: Si è verificato un errore per il quale non esiste un SQLSTATE specifico e per il quale non è stato definito sqlSTATE specifico dell'implementazione. Il messaggio di errore restituito da SQLGetDiagRec nell'argomento * MessageText buffer descrive l'errore e la relativa causa.
HY001 Errore di allocazione della memoria Il driver non è riuscito ad allocare la memoria necessaria per supportare l'esecuzione o il completamento della funzione.
HY010 Errore della sequenza di funzione È stata chiamata una funzione correlata all'istruzione in esecuzione in modo asincrono per uno degli handle di istruzione associati a Handle e HandleType è stato impostato su SQL_HANDLE_DBC. La funzione asincrona era ancora in esecuzione quando è stato chiamato SQLCancelHandle.

(DM) L'argomento HandleType è stato SQL_HANDLE_STMT; Una funzione in esecuzione in modo asincrono è stata chiamata sull'handle di connessione associato. e la funzione era ancora in esecuzione quando è stata chiamata questa funzione.

(DM) SQLExecute, SQLExecDirect o SQLMoreResults è stato chiamato per uno degli handle di istruzione associati a Handle e HandleType è stato impostato su SQL_HANDLE_DBC e restituito SQL_PARAM_DATA_AVAILABLE. Questa funzione è stata chiamata prima del recupero dei dati per tutti i parametri trasmessi.

SQLBrowseConnect è stato chiamato per ConnectionHandle e ha restituito SQL_NEED_DATA. Questa funzione è stata chiamata prima del completamento del processo di esplorazione.
HY013 Errore di gestione della memoria Non è stato possibile elaborare la chiamata di funzione perché non è stato possibile accedere agli oggetti di memoria sottostanti, probabilmente a causa di condizioni di memoria insufficiente.
HY092 Identificatore di attributo/opzione non valido HandleType è stato impostato su SQL_HANDLE_ENV o SQL_HANDLE_DESC.
HY117 La connessione è stata sospesa a causa di uno stato di transazione sconosciuto. Sono consentite solo le funzioni di disconnessione e di sola lettura. (DM) Per altre informazioni sullo stato sospeso, vedere Funzione SQLEndTran.
HYT01 Timeout della connessione scaduto Il periodo di timeout della connessione è scaduto prima che l'origine dati risponda alla richiesta. Il periodo di timeout della connessione viene impostato tramite SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Il driver non supporta questa funzione (DM) Il driver associato all'handle non supporta la funzione .

Se SQLCancelHandle viene chiamato con HandleType impostato su SQL_HANDLE_STMT, può restituire qualsiasi SQLSTATE che può essere restituito dalla funzione SQLCancel.

Commenti

Questa funzione è simile a SQLCancel, ma può assumere un handle di connessione o di istruzione come parametro anziché solo un handle di istruzione. Gestione driver esegue il mapping di una chiamata a SQLCancelHandle a una chiamata a SQLCancel quando HandleType è SQL_HANDLE_STMT. In questo modo le applicazioni possono usare SQLCancelHandle per annullare le operazioni delle istruzioni anche se il driver non implementa SQLCancelHandle.

Per altre informazioni sull'annullamento di un'operazione di istruzione, vedere Funzione SQLCancel.

Se non sono in corso operazioni su Handle, la chiamata a SQLCancelHandle non ha alcun effetto.

SQLCancelHandle su un handle di connessione può annullare i tipi di elaborazione seguenti:

  • Funzione in esecuzione in modo asincrono sulla connessione.

  • Funzione in esecuzione sull'handle di connessione in un altro thread.

Quando sqlCancelHandle viene chiamato per annullare una funzione in esecuzione in modo asincrono in una connessione, i record di diagnostica inviati da SQLCancelHandle vengono aggiunti a quelli restituiti dall'operazione annullata; SQLCancelHandle, tuttavia, non restituisce record di diagnostica quando si annulla una funzione in esecuzione su una connessione in un altro thread.

L'uso di SQLCancelHandle per annullare SQLEndTran può mettere la connessione in stato sospeso. Per altre informazioni sullo stato sospeso, vedere Funzione SQLEndTran.

Nota

Per informazioni su come usare SQLCancelHandle in un'applicazione che verrà distribuita in un sistema operativo Windows precedente a Windows 7, vedere Matrice di compatibilità.

Se una funzione restituisce SQL_STILL_EXECUTING, un'applicazione può chiamare SQLCancelHandle per annullare l'operazione. Se la richiesta di annullamento ha esito positivo, SQLCancelHandle restituisce SQL_SUCCESS. Ciò non significa che la funzione originale è stata annullata. indica che la richiesta di annullamento è stata elaborata. Il driver e l'origine dati determinano quando o se l'operazione viene annullata. L'applicazione deve continuare a chiamare la funzione originale finché il codice restituito non viene SQL_STILL_EXECUTING. Se la funzione originale è stata annullata, il codice restituito SQL_ERROR e SQLSTATE HY008 (Operazione annullata). Se la funzione originale ha completato la normale elaborazione (non annullata), il codice restituito è SQL_SUCCESS o SQL_SUCCESS_WITH_INFO o SQL_ERROR e un VALORE SQLSTATE diverso da HY008 (Operazione annullata), se la funzione originale non è riuscita.

Annullamento di funzioni in esecuzione in un altro thread

In un'applicazione multithread, l'applicazione può annullare un'operazione in esecuzione in un altro thread. Per annullare l'operazione, l'applicazione chiama SQLCancelHandle con l'handle usato dalla funzione, ma in un thread diverso. Il driver e il sistema operativo determinano la modalità di annullamento dell'operazione. Il codice restituito SQLCancelHandle indica se il driver ha elaborato la richiesta, SQL_SUCCESS o SQL_ERROR (non vengono restituite informazioni di diagnostica). Se l'elaborazione sulla funzione originale viene annullata, la funzione originale restituisce SQL_ERROR e SQLSTATE HY008 (Operazione annullata).

Se una funzione viene eseguita quando SQLCancelHandle viene chiamato su un altro thread per annullare la funzione, è possibile che la funzione riesca e restituirà SQL_SUCCESS prima che l'annullamento possa essere reso attivo. Una chiamata a SQLCancelHandle non ha alcun effetto se l'operazione è stata completata prima che SQLCancelHandle fosse in grado di annullare l'operazione.

Per informazioni su Vedere
Annullamento di una funzione in esecuzione in modo asincrono in un handle di istruzione, annullamento di una funzione in un'istruzione che richiede dati o annullamento di una funzione in esecuzione in un'istruzione in un altro thread. Funzione SQLCancel

Vedere anche

Informazioni di riferimento sulle API ODBC
File di intestazione ODBC
Esecuzione asincrona (metodo di polling)