Funzione SQLCancel

  • Articolo

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.

Resi

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

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

Vedi anche

Riferimento API ODBC
File di intestazione ODBC