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. Se un driver non lo fa, Una chiamata a SQLCancelHandle con un handle di connessione nel parametro Handle restituirà SQL_ERROR con SQLSTATE im001 e il messaggio 'Driver non supporta questa funzione'' Una chiamata per sqlCancelHandle con un handle di istruzione come parametro handle verrà eseguito il mapping 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.

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 annullare l'elaborazione. 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.

Rendiconto

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

La tabella seguente elenca i valori SQLSTATE comunemente restituiti da SQLCancelHandle e spiega ognuno 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 aggiunti 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 di Connection-Related

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 SQLCancelHand le 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 chiamata su un altro thread per annullare la funzione, è possibile che la funzione abbia esito positivo e restituisca SQL_SUCCESS prima che l'annullamento possa essere effettivo. Una chiamata a SQLCancelHandle non ha alcun effetto se l'operazione è stata completata prima di SQLCancelHandle è stata in grado di annullare l'operazione.

Funzioni correlate

Vedere anche

di riferimento all'API ODBC
file di intestazione ODBC
'esecuzione asincrona (metodo di polling)