SQLCancel, fonction

Conformité
Version introduite : Conformité aux normes ODBC 1.0 : ISO 92

Résumé
SQLCancel annule le traitement sur une instruction.

Pour annuler le traitement sur une connexion ou une instruction, utilisez la fonction SQLCancelHandle.

Syntaxe

  
SQLRETURN SQLCancel(  
     SQLHSTMT     StatementHandle);  

Arguments

StatementHandle
[Entrée] Handle d’instruction.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Lorsque SQLCancel retourne SQL_ERROR ou SQL_SUCCESS_WITH_INFO, une valeur SQLSTATE associée peut être obtenue en appelant SQLGetDiagRec avec un HandleType de SQL_HANDLE_STMT et un Handle of StatementHandle. Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLCancel et explique chacune d’elles dans le contexte de cette fonction ; la notation « (DM) » précède les descriptions des SQLSTATEs retournées par le Gestionnaire de pilotes. Le code de retour associé à chaque valeur SQLSTATE est SQL_ERROR, sauf indication contraire.

Commentaires

SQLCancel peut annuler les types de traitement suivants sur une instruction :

• Fonction s’exécutant de façon asynchrone sur l’instruction.

• Fonction sur une instruction qui a besoin de données.

• Fonction s’exécutant sur l’instruction sur un autre thread.

Dans ODBC 2.x, si une application appelle SQLCancel lorsqu’aucun traitement n’est effectué sur l’instruction, SQLCancel a le même effet que SQLFreeStmt avec l’option SQL_CLOSE ; ce comportement est défini uniquement pour l’exhaustivité et les applications doivent appeler SQLFreeStmt ou SQLCloseCursor pour fermer les curseurs.

Lorsque SQLCancel est appelé pour annuler une fonction exécutée de manière asynchrone dans une instruction ou une fonction sur une instruction qui a besoin de données, les enregistrements de diagnostic publiés par la fonction annulée sont effacés et SQLCancel publie ses propres enregistrements de diagnostic ; quand SQLCancel est appelé pour annuler une fonction exécutée sur une instruction sur un autre thread, toutefois, il ne efface pas les enregistrements de diagnostic de la fonction annulée et ne publie pas ses propres enregistrements de diagnostic.

Annulation du traitement asynchrone

Une fois qu’une application appelle une fonction de façon asynchrone, elle appelle la fonction à plusieurs reprises pour déterminer s’il a terminé le traitement. Si la fonction est toujours en cours de traitement, elle retourne SQL_STILL_EXECUTING. Si la fonction a terminé le traitement, elle retourne un code différent.

Après un appel à la fonction qui retourne SQL_STILL_EXECUTING, une application peut appeler SQLCancel pour annuler la fonction. Si la demande d’annulation réussit, le pilote retourne SQL_SUCCESS. Ce message n’indique pas que la fonction a été réellement annulée ; elle indique que la demande d’annulation a été traitée. Quand ou si la fonction est réellement annulée dépend du pilote et de la source de données. L’application doit continuer à appeler la fonction d’origine jusqu’à ce que le code de retour ne soit pas SQL_STILL_EXECUTING. Si la fonction a été annulée avec succès, le code de retour est SQL_ERROR et SQLSTATE HY008 (Opération annulée). Si la fonction a terminé son traitement normal, le code de retour est SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO si la fonction a réussi ou SQL_ERROR et un SQLSTATE autre que HY008 (Opération annulée) si la fonction a échoué.

Pour plus d’informations sur le traitement asynchrone, consultez Exécution asynchrone.

Annulation des fonctions qui ont besoin de données

Une fois que SQLExecute ou SQLExecDirect retourne SQL_NEED_DATA et avant que les données n’ont été envoyées pour tous les paramètres de données au niveau de l’exécution, une application peut appeler SQLCancel pour annuler l’exécution de l’instruction. Une fois l’instruction annulée, l’application peut appeler à nouveau SQLExecute ou SQLExecDirect . Pour plus d’informations, consultez SQLBindParameter.

Une fois QUE SQLBulkOperations ou SQLSetPos retourne SQL_NEED_DATA et avant que les données n’ont été envoyées pour toutes les colonnes de données au niveau de l’exécution, une application peut appeler SQLCancel pour annuler l’opération. Une fois l’opération annulée, l’application peut appeler à nouveau SQLBulkOperations ou SQLSetPos ; l’annulation n’affecte pas l’état du curseur ou la position actuelle du curseur. Pour plus d’informations, consultez SQLBulkOperations ou SQLSetPos.

Annulation des fonctions en cours d’exécution sur un autre thread

Dans une application multithread, l’application peut annuler une fonction qui s’exécute sur un autre thread. Pour annuler la fonction, l’application appelle SQLCancel avec le même handle d’instruction que celui utilisé par la fonction cible, mais sur un autre thread. La façon dont la fonction est annulée dépend du pilote et du système d’exploitation. Comme dans l’annulation d’une fonction en cours d’exécution asynchrone, le code de retour de SQLCancel indique uniquement si le pilote a traité la requête avec succès. Seuls SQL_SUCCESS ou SQL_ERROR peuvent être retournés ; aucune information de diagnostic n’est retournée. Si la fonction d’origine est annulée, elle retourne SQL_ERROR et SQLSTATE HY008 (Opération annulée).

Si une instruction SQL est exécutée lorsque SQLCancel est appelé sur un autre thread pour annuler l’exécution de l’instruction, il est possible que l’exécution réussisse et retourne SQL_SUCCESS pendant que l’annulation réussit également. Dans ce cas, le Gestionnaire de pilotes suppose que le curseur ouvert par l’exécution de l’instruction est fermé par l’annulation, de sorte que l’application ne pourra pas utiliser le curseur.

Pour plus d’informations sur le threading, consultez Multithreading.

Fonctions connexes

Voir aussi

Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC