Funzione SQLCancelHandle

  • Articolo

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.

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 è stato specificato SQLSTATE e per il quale non è stato definito alcun 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 memoria necessaria per supportare l'esecuzione o il completamento della funzione.
HY010 Errore della sequenza di funzioni È stata chiamata una funzione correlata all'istruzione in modo asincrono per uno degli handle di istruzione associati all'handle e HandleType è stata impostata su SQL_HANDLE_DBC. La funzione asincrona era ancora in esecuzione quando è stato chiamato SQLCancelHandle .

(DM) L'argomento HandleType è stato SQL_HANDLE_STMT; è stata chiamata una funzione in esecuzione asincrona 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 Impossibile 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 viene sospesa a causa dello stato sconosciuto della transazione. Sono consentite solo funzioni disconnesse e di sola lettura. (DM) Per altre informazioni sullo stato sospeso, vedere Funzione SQLEndTran.
HYT01 Il timeout della connessione è scaduto Periodo di timeout della connessione scaduto prima che l'origine dati rispondesse 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ò 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.

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 è 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.

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

Vedi anche

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