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.

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.

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

Voir aussi

Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC
Exécution asynchrone (méthode d’interrogation)