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.

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.

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

Vedi anche

Riferimento API ODBC
File di intestazione ODBC