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 SQLSTATE di IM001 e il messaggio 'Driver non supporta questa funzione'' Una chiamata a SQLCancelHandle con un handle di istruzione come parametro Handle verrà mappata a una chiamata a SQLCancel da Gestione driver e può essere elaborata se il driver implementa SQLCancel. Un'applicazione può usare SQLGetFunctions per determinare se un driver supporta SQLCancelHandle.

Riepilogo
SQLCancelHandle annulla l'elaborazione in 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 sono 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.

Resi

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 handle HandleType di SQL_HANDLE_STMT e un handle di istruzione Handle o HandleType di SQL_HANDLE_DBC e un handle di connessione.

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

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ò accettare una connessione o un handle 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. Ciò consente alle applicazioni di usare SQLCancelHandle per annullare le operazioni di istruzione 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 in 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 pubblicati da SQLCancelHandle vengono accodati a quelli restituiti dall'operazione annullata; SQLCancelHandle non restituisce record di diagnostica, tuttavia, quando si annulla una funzione in esecuzione su una connessione in un altro thread.

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

Annullamento dell'elaborazione asincrona correlata alla connessione

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 è SQL_STILL_EXECUTING. Se la funzione originale è stata annullata, il codice restituito viene SQL_ERROR e SQLSTATE HY008 (operazione annullata). Se la funzione originale ha completato la normale elaborazione (non è stata annullata), il codice restituito viene SQL_SUCCESS o SQL_SUCCESS_WITH_INFO oppure SQL_ERROR e sqlSTATE diverso da HY008 (operazione annullata), se la funzione originale non è riuscita.

Annullamento delle 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, restituendo SQL_SUCCESS o SQL_ERROR (non vengono restituite informazioni di diagnostica). Se l'elaborazione nella funzione originale viene annullata, la funzione originale restituisce SQL_ERROR e SQLSTATE HY008 (operazione annullata).

Se viene eseguita una funzione quando SQLCancelHandle viene chiamato su un altro thread per annullare la funzione, è possibile che la funzione abbia esito positivo e restituisca SQL_SUCCESS prima che l'annullamento possa avere effetto. Una chiamata a SQLCancelHandle non ha alcun effetto se l'operazione è stata completata prima che SQLCancelHandle fosse in grado di annullare l'operazione.

Funzioni correlate

Vedi anche

Riferimento API ODBC
File di intestazione ODBC
Esecuzione asincrona (metodo di polling)