SQLCancelHandle, fonction
conformité
Version introduite : Conformité aux normes ODBC 3.8 : Aucun
Il est prévu que la plupart des pilotes ODBC 3.8 (et versions ultérieures) implémentent cette fonction. Si un pilote ne le fait pas, un appel à SQLCancelHandle avec un handle de connexion dans le paramètre handle Handle retourne SQL_ERROR avec un SQLSTATE de IM001 et le message « Driver ne prend pas en charge cette fonction » A appel à SQLCancelHandle avec un handle d’instruction, car le paramètre handle Handle sera mappé à un appel à SQLCancel par le Gestionnaire de pilotes et peut être traité si le pilote implémente sqlCancel. Une application peut utiliser SQLGetFunctions pour déterminer si un pilote prend en charge SQLCancelHandle.
résumé
SQLCancelHandle annule le traitement sur une connexion ou une instruction. Le Gestionnaire de pilotes mappe un appel à SQLCancelHandle à un appel à SQLCancel lorsque handleType est SQL_HANDLE_STMT.
Syntaxe
SQLRETURN SQLCancelHandle(
SQLSMALLINT HandleType,
SQLHANDLE Handle);
Arguments
HandleType
[Entrée] Type du handle sur lequel annuler le traitement. Les valeurs valides sont SQL_HANDLE_DBC ou SQL_HANDLE_STMT.
Handle
[Entrée] Handle sur lequel annuler le traitement.
Si Handle n’est pas un handle valide du type spécifié par HandleType, SQLCancelHandle retourne SQL_INVALID_HANDLE.
Retourne
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnostic
Lorsque
Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLCancelHandle 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 tampon 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 | Une fonction liée à l’instruction en cours d’exécution asynchrone a été appelée pour l’un des handles d’instruction associés à l'handle (DM) L’argument handleType (DM) SQLBrowseConnect a été appelé pour ConnectionHandle et a retourné SQL_NEED_DATA. Cette fonction a été appelée avant la fin du processus de navigation. |
| 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. |
| HY092 | Identificateur d’attribut/d’option non valide | handleType a été défini sur SQL_HANDLE_ENV ou SQL_HANDLE_DESC. |
| 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 | Expiration du délai d’expiration de la connexion | 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 la connexion est définie via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Le pilote ne prend pas en charge cette fonction | (DM) Le pilote associé à la Handle ne prend pas en charge la fonction. |
Si SQLCancelHandle est appelé avec HandleType défini sur SQL_HANDLE_STMT, il peut retourner n’importe quel SQLSTATE qui peut être retourné par la fonction SQLCancel.
Commentaires
Cette fonction est similaire à SQLCancel, mais peut prendre un handle de connexion ou d’instruction comme paramètre plutôt qu’un handle d’instruction. Le Gestionnaire de pilotes mappe un appel à SQLCancelHandle à un appel à SQLCancel lorsque handleType est SQL_HANDLE_STMT. Cela permet aux applications d’utiliser SQLCancelHandle pour annuler les opérations d’instruction même si le pilote n’implémente pas SQLCancelHandle.
Pour plus d’informations sur l’annulation d’une opération d’instruction, consultez fonction SQLCancel.
S’il n’existe aucune opération en cours sur Handle l’appel à SQLCancelHandle n’a aucun effet.
SQLCancelHandle sur un handle de connexion peut annuler les types de traitement suivants :
Fonction s’exécutant de manière asynchrone sur la connexion.
Fonction s’exécutant sur le handle de connexion sur un autre thread.
Lorsque SQLCancelHandle est appelé pour annuler une fonction exécutée de manière asynchrone dans une connexion, les enregistrements de diagnostic publiés par SQLCancelHandle sont ajoutés à ceux retournés par l’opération en cours d’annulation ; SQLCancelHandle ne retourne pas d’enregistrements de diagnostic, toutefois, lors de l’annulation d’une fonction s’exécutant sur une connexion sur un autre thread.
L’utilisation de SQLCancelHandle pour annuler SQLEndTran peut mettre la connexion en état suspendu. Pour plus d’informations sur l’état suspendu, consultez fonction SQLEndTran.
Note
Pour plus d’informations sur l’utilisation de SQLCancelHandle dans une application qui sera déployée sur un système d’exploitation Windows antérieur à Windows 7, consultez matrice de compatibilité.
Annulation du traitement asynchrone Connection-Related
Si une fonction retourne SQL_STILL_EXECUTING, une application peut appeler SQLCancelHandle pour annuler l’opération. Si la demande d’annulation réussit, SQLCancelHandle retourne SQL_SUCCESS. Cela ne signifie pas que la fonction d’origine a été annulée ; elle indique que la demande d’annulation a été traitée. Le pilote et la source de données déterminent quand ou si l’opération est annulée. 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 d’origine a été annulée, le code de retour est SQL_ERROR et SQLSTATE HY008 (Opération annulée). Si la fonction d’origine a terminé son traitement normal (n’a pas été annulé), le code de retour est SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO, ou SQL_ERROR et un SQLSTATE autre que HY008 (Opération annulée), si la fonction d’origine a échoué.
Annulation des fonctions en cours d’exécution sur un autre thread
Dans une application multithread, l’application peut annuler une opération qui s’exécute sur un autre thread. Pour annuler l’opération, l’application appelle SQLCancelHandle avec le handle utilisé par la fonction, mais sur un autre thread. Le pilote et le système d’exploitation déterminent la façon dont l’opération est annulée. Le code de retour SQLCancelHandle indique si le pilote a traité la requête, en retournant SQL_SUCCESS ou SQL_ERROR (aucune information de diagnostic n’est retournée). Si le traitement sur la fonction d’origine est annulé, la fonction d’origine retourne SQL_ERROR et SQLSTATE HY008 (Opération annulée).
Si une fonction est exécutée lorsque SQLCancelHandle est appelé sur un autre thread pour annuler la fonction, il est possible que la fonction réussisse et retourne SQL_SUCCESS avant que l’annulation ne prenne effet. Un appel à SQLCancelHandle n’a aucun effet si l’opération s’est terminée avant SQLCancelHandle a pu annuler l’opération.
Fonctions associées
| Pour plus d’informations sur | Voir |
|---|---|
| Annulation d’une fonction exécutée de manière asynchrone sur un handle d’instruction, annulation d’une fonction sur une instruction qui a besoin de données ou annulation d’une fonction s’exécutant sur une instruction sur un autre thread. | fonction SQLCancel |
Voir aussi
informations de référence sur l’API ODBC
fichiers d’en-tête ODBC
exécution asynchrone (méthode d’interrogation)