SQLCancelHandle, fonction
Conformité
Version introduite : Conformité aux normes ODBC 3.8 : Aucune
Il est prévu que la plupart des pilotes ODBC 3.8 (et versions ultérieures) implémentent cette fonction. Si ce n’est pas le cas d’un pilote, un appel à SQLCancelHandle avec un handle de connexion dans le paramètre Handle renvoie SQL_ERROR avec un SQLSTATE d’IM001 et le message « Driver ne prend pas en charge cette fonction » Un appel à SQLCancelHandle avec un handle d’instruction en tant que paramètre 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 le traitement doit être cacelé. 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.
Retours
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnostics
Lorsque SQLCancelHandle 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 d’instruction Handle ou un HandleType d’SQL_HANDLE_DBC et un handle de connexion Handle.
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 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 | 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 au handle, et HandleType a été défini sur SQL_HANDLE_DBC. La fonction asynchrone était toujours en cours d’exécution lorsque SQLCancelHandle a été appelé. (DM) L’argument HandleType a été SQL_HANDLE_STMT ; une fonction d’exécution asynchrone a été appelée sur le handle de connexion associé ; et la fonction était toujours en cours d’exécution lorsque cette fonction a été appelée. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults a été appelé pour l’un des handles d’instruction associés à Handle etHandleType a été défini sur SQL_HANDLE_DBC et a renvoyé SQL_PARAM_DATA_AVAILABLE. Cette fonction a été appelée avant la récupération des données pour tous les paramètres diffusés. 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 consultés, peut-être 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 | 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 réponde à la demande. La période de délai 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é au 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 en tant que paramètre plutôt qu’un handle d’instruction uniquement. 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.
Si aucune opération n’est 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 à l’état suspendu. Pour plus d’informations sur l’état suspendu, consultez Fonction SQLEndTran.
Notes
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 de fonctions exécutées 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 thread différent. 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 demande, 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 quand 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 que SQLCancelHandle ait pu annuler l’opération.
Fonctions connexes
| Pour obtenir des informations sur | Consultez |
|---|---|
| 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. | SQLCancel, fonction |
Voir aussi
Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC
Exécution asynchrone (méthode d’interrogation)