Funzione SQLCancel

Conformità
Versione introdotta: Conformità agli standard ODBC 1.0: ISO 92

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

Restituisce

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 un HandleType di SQL_HANDLE_STMT e un Handle di StatementHandle. Nella tabella seguente sono elencati i valori SQLSTATE comunemente restituiti da SQLCancel e vengono illustrati 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 venga 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 definito un SQLSTATE specifico e per il quale non è stato definito ALCUN VALORE 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 è stato in grado di allocare la 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.

(DM) Operazione di annullamento non riuscita perché è in corso un'operazione asincrona 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 è stata sospesa a causa di uno stato di transazione sconosciuto. Sono consentite solo funzioni di disconnessione e di sola lettura. (DM) Per altre informazioni sullo stato sospeso, vedere Funzione SQLEndTran.
HYT01 Timeout della connessione scaduto Il periodo di timeout della connessione è scaduto prima che l'origine dati risponda 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 sull'istruzione .

  • Funzione in un'istruzione che richiede 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 sull'istruzione , SQLCancel ha lo stesso effetto di SQLFreeStmt con l'opzione SQL_CLOSE; Questo comportamento è definito solo per completezza e le applicazioni devono chiamare SQLFreeStmt o SQLCloseCursor per chiudere i cursori.

Quando viene chiamato SQLCancel per annullare una funzione in esecuzione in modo asincrono in un'istruzione o in una funzione in un'istruzione che richiede dati, i record di diagnostica inviati dalla funzione annullata vengono cancellati e SQLCancel invia i propri record di diagnostica. Quando sqlCancel viene chiamato per annullare una funzione in esecuzione in un'istruzione in un altro thread, tuttavia, non cancella i record di diagnostica della funzione annullata e non registra 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 fase di elaborazione, restituisce SQL_STILL_EXECUTING. Se la funzione ha terminato l'elaborazione, 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, dipende dal driver e dall'origine dati. L'applicazione deve continuare a chiamare la funzione originale finché il codice restituito non viene SQL_STILL_EXECUTING. Se la funzione è stata annullata correttamente, il codice restituito SQL_ERROR e SQLSTATE HY008 (operazione annullata). Se la funzione ha completato la normale elaborazione, il codice restituito è SQL_SUCCESS o SQL_SUCCESS_WITH_INFO se la funzione ha avuto esito positivo o SQL_ERROR e un valore SQLSTATE diverso da HY008 (operazione annullata) se la funzione ha avuto esito negativo.

Nota

In ODBC 3.5 una chiamata a SQLCancel quando non viene eseguita alcuna elaborazione sull'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 necessitano di dati

Dopo che SQLExecute o SQLExecDirect ha restituito SQL_NEED_DATA e prima che i dati siano stati inviati per tutti i parametri data-at-execution, 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 ha restituito SQL_NEED_DATA e prima che i dati siano stati inviati per tutte le colonne di dati in fase di esecuzione, 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 SQL_SUCCESS o SQL_ERROR solo i dati. Non vengono restituite informazioni di diagnostica. Se la funzione originale viene annullata, restituisce SQL_ERROR e SQLSTATE HY008 (operazione annullata).

Se un'istruzione SQL viene eseguita quando viene chiamato SQLCancel su un altro thread per annullare l'esecuzione dell'istruzione, è possibile che l'esecuzione venga completata correttamente e restituirà SQL_SUCCESS mentre l'annullamento ha esito positivo. In questo caso, Gestione driver presuppone che il cursore aperto dall'esecuzione dell'istruzione sia 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 Pagina relativa alla 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'istruzione 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 cui inviare i dati Funzione SQLParamData
Invio dei dati dei parametri in fase di esecuzione SQLPutData Function
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

Vedere anche

Informazioni di riferimento sulle API ODBC
File di intestazione ODBC