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 d’une connexion ou d’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 handled’instructionHandle. 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 de SQLSTATEs retournées par le Gestionnaire de pilotes. Le code de retour associé à chaque valeur SQLSTATE est SQL_ERROR, sauf indication contraire.

SQLSTATE Error 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 pas de SQLSTATE spécifique et pour laquelle aucun SQLSTATE spécifique à l’implémentation n’a été défini. Le message d’erreur retourné par SQLGetDiagRec dans l’argument *Mémoire tampon MessageText décrit l’erreur et sa cause.
HY001 Erreur d’allocation de mémoire Le pilote n’a pas pu allouer la 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 exécution asynchrone a été appelée pour le handle de connexion associé à l’InstructionHandle. Cette fonction asynchrone était toujours en cours d’exécution lorsque la fonction SQLCancel a été appelée.

(DM) Échec de l’opération d’annulation, 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, peut-être 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 Fonction SQLEndTran.
HYT01 Délai d’attente de la connexion expiré Le délai d’expiration de la connexion a expiré avant que la source de données ne réponde à la demande. Le délai d’expiration de connexion est défini via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Le pilote ne prend pas en charge cette fonction (DM) Le pilote associé à l’InstructionHandle ne prend pas en charge la fonction .

Commentaires

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

  • Fonction s’exécutant de manière 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 quand 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 s’exécutant de façon 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 en cours d’annulation sont effacés et SQLCancel publie ses propres enregistrements de diagnostic ; Toutefois, quand SQLCancel est appelé pour annuler une fonction en cours d’exécution sur une instruction sur un autre thread, il n’efface pas les enregistrements de diagnostic de la fonction en cours d’annulation et ne publie pas ses propres enregistrements de diagnostic.

Annulation du traitement asynchrone

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

Après tout 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, 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é.

Notes

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. 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 a retourné SQL_NEED_DATA et avant que les données n’ont été envoyées pour tous les paramètres de données en cours d’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 a retourné SQL_NEED_DATA et avant que les données n’ont été envoyées pour toutes les colonnes de données lors 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 de fonctions exécutées sur un autre thread

Dans une application multithread, l’application peut annuler une fonction en cours d’exécution 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 thread différent. La façon dont la fonction est annulée dépend du pilote et du système d’exploitation. Comme lors de 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 tandis 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 obtenir des informations sur Consultez
Liaison d’une mémoire tampon à un paramètre Fonction SQLBindParameter
Exécution d’opérations d’insertion ou de mise à jour en bloc SQLBulkOperations, fonction
Annule une fonction s’exécutant de façon 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 Fonction SQLGetDiagField
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 Fonction SQLPutData
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