Partage via

SQLCancel, fonction

  • Article

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.

SQLSTATE Erreur Description
01000 Avertissement général Message d’information spécifique au pilote. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
HY000 Erreur générale Une erreur s’est produite pour laquelle il n’y avait aucun SQLSTATE spécifique et pour lequel aucun SQLSTATE spécifique à l’implémentation n’a été défini. Le message d’erreur retourné par SQLGetDiagRec dans l’argument *MessageText buffer décrit l’erreur et sa cause.
HY001 Erreur d’allocation de mémoire Le pilote n’a pas pu allouer de mémoire nécessaire pour prendre en charge l’exécution ou l’achèvement de la fonction.
HY010 Erreur de séquence de fonction (DM) Une fonction en cours d’exécution asynchrone a été appelée pour le handle de connexion associé à StatementHandle. Cette fonction asynchrone était toujours en cours d’exécution lorsque la fonction SQLCancel a été appelée.

Échec de l’opération d’annulation (DM) car une opération asynchrone est en cours sur un handle de connexion associé à StatementHandle.
HY013 Erreur de gestion de la mémoire L’appel de fonction n’a pas pu être traité, car les objets de mémoire sous-jacents n’ont pas pu être accessibles, éventuellement en raison de conditions de mémoire insuffisantes.
HY018 Demande d’annulation refusée par le serveur Le serveur a refusé la demande d’annulation.
HY117 La connexion est suspendue en raison d’un état de transaction inconnu. Seules les fonctions de déconnexion et de lecture seule sont autorisées. (DM) Pour plus d’informations sur l’état suspendu, consultez la fonction SQLEndTran.
HYT01 Délai d’attente de la connexion expiré La période d’expiration de la connexion a expiré avant que la source de données ne réponde à la demande. La période d’expiration de connexion est définie via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Le pilote ne prend pas en charge cette fonction (DM) Le pilote associé à StatementHandle ne prend pas en charge la fonction.

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

Remarque

Dans ODBC 3.5, un appel à SQLCancel lorsqu’aucun traitement n’est effectué sur l’instruction n’est pas traité comme SQLFreeStmt avec l’option SQL_CLOSE, mais n’a aucun effet du tout. Pour fermer un curseur, une application doit appeler SQLCloseCursor, et non SQLCancel.

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.

Pour plus d’informations sur Consultez
Liaison d’une mémoire tampon à un paramètre SQLBindParameter, fonction
Exécution d’opérations d’insertion ou de mise à jour en bloc SQLBulkOperations, fonction
Annule une fonction s’exécutant de manière asynchrone sur un handle de connexion, en plus des fonctionnalités de SQLCancel. SQLCancelHandle, fonction
Exécution d’une instruction SQL SQLExecDirect, fonction
Exécution d’une instruction SQL préparée SQLExecute, fonction
Libération d’un handle d’instruction SQLFreeStmt
Obtention d’un champ d’un enregistrement de diagnostic ou d’un champ de l’en-tête de diagnostic SQLGetDiagField, fonction
Obtention de plusieurs champs d’une structure de données de diagnostic SQLGetDiagRec, fonction
Retour du paramètre suivant pour lequel envoyer des données SQLParamData, fonction
Envoi de données de paramètre au moment de l’exécution SQLPutData, fonction
Positionnement du curseur dans un ensemble de lignes, actualisation des données dans l’ensemble de lignes ou mise à jour ou suppression de données dans le jeu de résultats SQLSetPos, fonction

Voir aussi

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