Funzione SQLCancel
Conformità
Versione introdotta: Conformità agli standard ODBC 1.0: ISO 92
Riepilogo
SQLCancel annulla l'elaborazione in un'istruzione .
Per annullare l'elaborazione in una connessione o un'istruzione, usare la funzione SQLCancelHandle.
Sintassi
SQLRETURN SQLCancel(
SQLHSTMT StatementHandle);
Argomenti
StatementHandle
[Input] Handle di istruzione.
Valori restituiti
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnostica
Quando SQLCancel 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 StatementHandle. La tabella seguente elenca i valori SQLSTATE comunemente restituiti da SQLCancel e ne 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.
| 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 | (DM) È stata chiamata una funzione in esecuzione asincrona per l'handle di connessione associato a StatementHandle. Questa funzione asincrona era ancora in esecuzione quando è stata chiamata la funzione SQLCancel . Operazione di annullamento non riuscita perché un'operazione asincrona è in corso su un handle di connessione associato a StatementHandle. |
| 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. |
| HY018 | Richiesta di annullamento rifiutata dal server | Il server ha rifiutato la richiesta di annullamento. |
| 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 a StatementHandle non supporta la funzione. |
Commenti
SQLCancel può annullare i tipi di elaborazione seguenti in un'istruzione :
Funzione in esecuzione in modo asincrono nell'istruzione .
Funzione in un'istruzione che necessita di dati.
Funzione in esecuzione sull'istruzione in un altro thread.
In ODBC 2.x, se un'applicazione chiama SQLCancel quando non viene eseguita alcuna elaborazione nell'istruzione, SQLCancel ha lo stesso effetto di SQLFreeStmt con l'opzione SQL_CLOSE. Questo comportamento viene definito solo per completezza e le applicazioni devono chiamare SQLFreeStmt o SQLCloseCursor per chiudere i cursori.
Quando SQLCancel viene chiamato per annullare una funzione in esecuzione in modo asincrono in un'istruzione o in un'istruzione che richiede dati, i record di diagnostica pubblicati dalla funzione annullata vengono cancellati e SQLCancel pubblica i propri record di diagnostica; quando SQLCancel viene chiamato per annullare una funzione in esecuzione su un'istruzione su un altro thread, tuttavia, non cancella i record di diagnostica della funzione annullata e non pubblica i propri record di diagnostica.
Annullamento dell'elaborazione asincrona
Dopo che un'applicazione chiama una funzione in modo asincrono, chiama ripetutamente la funzione per determinare se l'elaborazione è stata completata. Se la funzione è ancora in elaborazione, restituisce SQL_STILL_EXECUTING. Se l'elaborazione della funzione è stata completata, restituisce un codice diverso.
Dopo qualsiasi chiamata alla funzione che restituisce SQL_STILL_EXECUTING, un'applicazione può chiamare SQLCancel per annullare la funzione. Se la richiesta di annullamento ha esito positivo, il driver restituisce SQL_SUCCESS. Questo messaggio non indica che la funzione è stata effettivamente annullata; indica che la richiesta di annullamento è stata elaborata. Quando o se la funzione viene effettivamente annullata è dipendente dal driver e dipendente dall'origine dati. L'applicazione deve continuare a chiamare la funzione originale finché il codice restituito non è SQL_STILL_EXECUTING. Se la funzione è stata annullata correttamente, il codice restituito viene SQL_ERROR e SQLSTATE HY008 (operazione annullata). Se la funzione ha completato la normale elaborazione, il codice restituito viene SQL_SUCCESS o SQL_SUCCESS_WITH_INFO se la funzione ha avuto esito positivo o SQL_ERROR e sqlSTATE diverso da HY008 (operazione annullata) se la funzione non è riuscita.
Nota
In ODBC 3.5, una chiamata a SQLCancel quando non viene eseguita alcuna elaborazione nell'istruzione non viene considerata come SQLFreeStmt con l'opzione SQL_CLOSE, ma non ha alcun effetto. Per chiudere un cursore, un'applicazione deve chiamare SQLCloseCursor, non SQLCancel.
Per altre informazioni sull'elaborazione asincrona, vedere Esecuzione asincrona.
Annullamento di funzioni che richiedono dati
Dopo che SQLExecute o SQLExecDirect restituisce SQL_NEED_DATA e prima che i dati siano stati inviati per tutti i parametri di esecuzione dei dati, un'applicazione può chiamare SQLCancel per annullare l'esecuzione dell'istruzione. Dopo l'annullamento dell'istruzione, l'applicazione può chiamare di nuovo SQLExecute o SQLExecDirect . Per altre informazioni, vedere SQLBindParameter.
Dopo che SQLBulkOperations o SQLSetPos restituisce SQL_NEED_DATA e prima che i dati siano stati inviati per tutte le colonne di esecuzione dei dati, un'applicazione può chiamare SQLCancel per annullare l'operazione. Dopo l'annullamento dell'operazione, l'applicazione può chiamare di nuovo SQLBulkOperations o SQLSetPos . L'annullamento non influisce sullo stato del cursore o sulla posizione corrente del cursore. Per altre informazioni, vedere SQLBulkOperations o SQLSetPos.
Annullamento delle funzioni in esecuzione in un altro thread
In un'applicazione multithread l'applicazione può annullare una funzione in esecuzione in un altro thread. Per annullare la funzione, l'applicazione chiama SQLCancel con lo stesso handle di istruzione usato dalla funzione di destinazione, ma in un thread diverso. La modalità di annullamento della funzione dipende dal driver e dal sistema operativo. Come nell'annullamento di una funzione in esecuzione in modo asincrono, il codice restituito di SQLCancel indica solo se il driver ha elaborato correttamente la richiesta. È possibile restituire solo SQL_SUCCESS o SQL_ERROR; non vengono restituite informazioni di diagnostica. Se la funzione originale viene annullata, restituisce SQL_ERROR e SQLSTATE HY008 (operazione annullata).
Se viene eseguita un'istruzione SQL quando SQLCancel viene chiamato su un altro thread per annullare l'esecuzione dell'istruzione, è possibile che l'esecuzione abbia esito positivo e restituisca SQL_SUCCESS mentre l'annullamento ha esito positivo. In questo caso, Gestione driver presuppone che il cursore aperto dall'esecuzione dell'istruzione venga chiuso dall'annullamento, quindi l'applicazione non sarà in grado di usare il cursore.
Per altre informazioni sul threading, vedere Multithreading.
Funzioni correlate
| Per informazioni su | Vedere |
|---|---|
| Associazione di un buffer a un parametro | Funzione SQLBindParameter |
| Esecuzione di operazioni di inserimento o aggiornamento bulk | Funzione SQLBulkOperations |
| Annulla una funzione in esecuzione in modo asincrono su un handle di connessione, oltre alla funzionalità di SQLCancel. | Funzione SQLCancelHandle |
| Esecuzione di un'istruzione SQL | Funzione SQLExecDirect |
| Esecuzione di un'istruzione SQL preparata | Funzione SQLExecute |
| Liberare un handle di istruzione | SQLFreeStmt |
| Recupero di un campo di un record di diagnostica o di un campo dell'intestazione di diagnostica | Funzione SQLGetDiagField |
| Recupero di più campi di una struttura di dati di diagnostica | Funzione SQLGetDiagRec |
| Restituzione del parametro successivo per l'invio di dati per | Funzione SQLParamData |
| Invio dei dati dei parametri in fase di esecuzione | Funzione SQLPutData |
| Posizionamento del cursore in un set di righe, aggiornamento dei dati nel set di righe o aggiornamento o eliminazione di dati nel set di risultati | Funzione SQLSetPos |