SQLEndTran, fonction
Conformité
Version introduite : Conformité aux normes ODBC 3.0 : ISO 92
Résumé
SQLEndTran demande une opération de validation ou de restauration pour toutes les opérations actives sur toutes les instructions associées à une connexion. SQLEndTran peut également demander qu’une opération de validation ou de restauration soit effectuée pour toutes les connexions associées à un environnement.
Remarque
Pour plus d’informations sur ce que le Gestionnaire de pilotes mappe cette fonction à lorsqu’une instance ODBC 3.x application fonctionne avec ODBC 2.Pilote x , consultez Fonctions de remplacement de mappage pour la compatibilité descendante des applications.
Syntaxe
SQLRETURN SQLEndTran(
SQLSMALLINT HandleType,
SQLHANDLE Handle,
SQLSMALLINT CompletionType);
Arguments
HandleType
[Entrée] Handle type identifier. Contient SQL_HANDLE_ENV (si Handle est un handle d’environnement) ou SQL_HANDLE_DBC (si Handle est un handle de connexion).
Poignée
[Entrée] Handle, du type indiqué par HandleType, indiquant l’étendue de la transaction. Pour plus d’informations, consultez « Commentaires ».
CompletionType
[Entrée] Une des deux valeurs suivantes :
SQL_COMMIT SQL_ROLLBACK
Retours
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE ou SQL_STILL_EXECUTING.
Diagnostics
Lorsque SQLEndTran retourne SQL_ERROR ou SQL_SUCCESS_WITH_INFO, une valeur SQLSTATE associée peut être obtenue en appelant SQLGetDiagRec avec le HandleType et handle appropriés. Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLEndTran 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.) |
| 08003 | Connexion non ouverte | (DM) HandleType était SQL_HANDLE_DBC et le handle n’était pas dans un état connecté. |
| 08007 | Échec de connexion pendant la transaction | HandleType a été SQL_HANDLE_DBC, et la connexion associée au handle a échoué pendant l’exécution de la fonction, et elle ne peut pas être déterminée si la validation demandée ou ROLLBACK s’est produite avant l’échec. |
| 25S01 | État de transaction inconnu | Une ou plusieurs connexions dans Handle n’ont pas pu terminer la transaction avec le résultat spécifié, et le résultat est inconnu. |
| 25S02 | La transaction est toujours active | Le pilote n’a pas pu garantir que tous les travaux de la transaction globale pourraient être terminés atomiquement et que la transaction est toujours active. |
| 25S03 | La transaction est restaurée | Le pilote n’a pas pu garantir que tous les travaux de la transaction globale pouvaient être terminés atomiquement et que tout le travail dans la transaction active dans Handle a été restauré. |
| 40001 | Échec de sérialisation | La transaction a été restaurée en raison d’un interblocage de ressources avec une autre transaction. |
| 40002 | Violation de contrainte d’intégrité | Le completionType a été SQL_COMMIT et l’engagement des modifications a provoqué une violation de contrainte d’intégrité. Par conséquent, la transaction a été restaurée. |
| 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 la mémoire tampon *szMessageText 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. |
| HY008 | Opération annulée | Le traitement asynchrone a été activé pour ConnectionHandle. La fonction a été appelée et avant de terminer l’exécution de la fonction SQLCancelHandle a été appelée sur ConnectionHandle. Ensuite, la fonction a été appelée à nouveau sur ConnectionHandle. La fonction a été appelée et avant de terminer l’exécution de SQLCancelHandle a été appelée sur connectionHandle à partir d’un autre thread dans une application multithread. |
| HY010 | Erreur de séquence de fonction | (DM) Une fonction en cours d’exécution asynchrone a été appelée pour un handle d’instruction associé à ConnectionHandle et était toujours en cours d’exécution lorsque SQLEndTran a été appelé. (DM) Une fonction en cours d’exécution asynchrone (et non celle-ci) a été appelée pour connectionHandle et était toujours en cours d’exécution lorsque cette fonction a été appelée. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos a été appelé pour un handle d’instruction associé à ConnectionHandle et retourné SQL_NEED_DATA. Cette fonction a été appelée avant que les données ne soient envoyées pour tous les paramètres ou colonnes de données à l’exécution. (DM) Une fonction en cours d’exécution asynchrone (pas celle-ci) a été appelée pour le handle avec HandleType défini sur SQL_HANDLE_DBC et s’exécutait toujours lorsque cette fonction était appelée. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults a été appelé pour l’un des handles d’instruction associés à Handle et retourné 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 en continu. |
| HY012 | Code d’opération de transaction non valide | (DM) La valeur spécifiée pour l’argument CompletionType n’était ni SQL_COMMIT ni SQL_ROLLBACK. |
| 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 | (DM) La valeur spécifiée pour l’argument HandleType n’était ni SQL_HANDLE_ENV ni SQL_HANDLE_DBC. |
| HY115 | SQLEndTran n’est pas autorisé pour un environnement qui contient une connexion avec l’exécution de fonction asynchrone activée | (DM) HandleType ne peut pas être défini sur SQL_HANDLE_ENV si l’exécution asynchrone des fonctions de connexion est activée pour une connexion dans l’environnement. |
| 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, reportez-vous à la section Commentaires de cette rubrique. |
| HYC00 | Fonctionnalité facultative non implémentée | Le pilote ou la source de données ne prend pas en charge l’opération ROLLBACK . |
| 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é à ConnectionHandle ne prend pas en charge la fonction. |
| IM017 | L’interrogation est désactivée en mode de notification asynchrone | Chaque fois que le modèle de notification est utilisé, l’interrogation est désactivée. |
| IM018 | SQLCompleteAsync n’a pas été appelé pour terminer l’opération asynchrone précédente sur ce handle. | Si l’appel de fonction précédent sur le handle retourne SQL_STILL_EXECUTING et si le mode de notification est activé, SQLCompleteAsync doit être appelé sur le handle pour effectuer un post-traitement et terminer l’opération. |
Commentaires
Pour un ODBC 3.x driver, si HandleType est SQL_HANDLE_ENV et Handle est un handle d’environnement valide, le Gestionnaire de pilotes appelle SQLEndTran dans chaque pilote associé à l’environnement. L’argument Handle de l’appel à un pilote sera le handle d’environnement du pilote. Pour un ODBC 2.X driver, si HandleType est SQL_HANDLE_ENV et Handle est un handle d’environnement valide et qu’il existe plusieurs connexions dans un état connecté dans cet environnement, le Gestionnaire de pilotes appelle SQLTransact dans le pilote une fois pour chaque connexion dans un état connecté dans cet environnement. L’argument Handle dans chaque appel sera le handle de la connexion. Dans les deux cas, le pilote tente de valider ou de restaurer des transactions, en fonction de la valeur de CompletionType, sur toutes les connexions qui se trouvent dans un état connecté sur cet environnement. Les connexions qui ne sont pas actives n’affectent pas la transaction.
Remarque
SQLEndTran ne peut pas être utilisé pour valider ou restaurer des transactions sur un environnement partagé. SQLSTATE HY092 (identificateur d’attribut/d’option non valide) est retourné si SQLEndTran est appelé avec Handle défini sur le handle d’un environnement partagé ou le handle d’une connexion sur un environnement partagé.
Le Gestionnaire de pilotes retourne SQL_SUCCESS uniquement s’il reçoit SQL_SUCCESS pour chaque connexion. Si le Gestionnaire de pilotes reçoit SQL_ERROR sur une ou plusieurs connexions, il retourne SQL_ERROR à l’application et les informations de diagnostic sont placées dans la structure des données de diagnostic de l’environnement. Pour déterminer quelles connexions ont échoué pendant l’opération de validation ou de restauration, l’application peut appeler SQLGetDiagRec pour chaque connexion.
Remarque
Le Gestionnaire de pilotes ne simule pas une transaction globale sur toutes les connexions et n’utilise donc pas de protocoles de validation en deux phases.
Si CompletionType est SQL_COMMIT, SQLEndTran émet une demande de validation pour toutes les opérations actives sur n’importe quelle instruction associée à une connexion affectée. Si CompletionType est SQL_ROLLBACK, SQLEndTran émet une demande de restauration pour toutes les opérations actives sur n’importe quelle instruction associée à une connexion affectée. Si aucune transaction n’est active, SQLEndTran retourne SQL_SUCCESS sans effet sur les sources de données. Pour plus d’informations, consultez Commiting and Rolling Back Transactions.
Si le pilote est en mode de validation manuelle (en appelant SQLSetConnectAttr avec l’attribut SQL_ATTR_AUTOCOMMIT défini sur SQL_AUTOCOMMIT_OFF), une nouvelle transaction est implicitement démarrée lorsqu’une instruction SQL pouvant être contenue dans une transaction est exécutée sur la source de données actuelle. Pour plus d’informations, consultez Le mode validation.
Pour déterminer comment les opérations de transaction affectent les curseurs, une application appelle SQLGetInfo avec les options SQL_CURSOR_ROLLBACK_BEHAVIOR et SQL_CURSOR_COMMIT_BEHAVIOR. Pour plus d’informations, consultez les paragraphes suivants, ainsi que l’effet des transactions sur les curseurs et les instructions préparées.
Si la valeur SQL_CURSOR_ROLLBACK_BEHAVIOR ou SQL_CURSOR_COMMIT_BEHAVIOR est égale à SQL_CB_DELETE, SQLEndTran ferme et supprime tous les curseurs ouverts sur toutes les instructions associées à la connexion et ignore tous les résultats en attente. SQLEndTran laisse une instruction présente dans un état alloué (non préparé) ; l’application peut les réutiliser pour les requêtes SQL suivantes ou appeler SQLFreeStmt ou SQLFreeHandle avec un HandleType de SQL_HANDLE_STMT pour les libérer.
Si la valeur SQL_CURSOR_ROLLBACK_BEHAVIOR ou SQL_CURSOR_COMMIT_BEHAVIOR est égale à SQL_CB_CLOSE, SQLEndTran ferme tous les curseurs ouverts sur toutes les instructions associées à la connexion. SQLEndTran laisse une instruction présente dans un état préparé ; l’application peut appeler SQLExecute pour une instruction associée à la connexion sans appeler SQLPrepare.
Si la valeur SQL_CURSOR_ROLLBACK_BEHAVIOR ou SQL_CURSOR_COMMIT_BEHAVIOR est égale à SQL_CB_PRESERVE, SQLEndTran n’affecte pas les curseurs ouverts associés à la connexion. Les curseurs restent à la ligne vers laquelle ils pointaient avant l’appel à SQLEndTran.
Pour les pilotes et les sources de données qui prennent en charge les transactions, l’appel de SQLEndTran avec SQL_COMMIT ou SQL_ROLLBACK lorsqu’aucune transaction n’est active retourne SQL_SUCCESS (indiquant qu’il n’y a pas de travail à commiter ou de restauration) et n’a aucun effet sur la source de données.
Lorsqu’un pilote est en mode de validation automatique, le Gestionnaire de pilotes n’appelle pas SQLEndTran dans le pilote. SQLEndTran retourne toujours SQL_SUCCESS qu’elle soit appelée avec un completionType de SQL_COMMIT ou de SQL_ROLLBACK.
Les pilotes ou les sources de données qui ne prennent pas en charge les transactions (l’option SQLGetInfo SQL_TXN_CAPABLE est SQL_TC_NONE) sont toujours en mode de validation automatique et retournent donc toujours SQL_SUCCESS pour SQLEndTran, qu’ils soient appelés avec un type d’achèvement de SQL_COMMIT ou de SQL_ROLLBACK. Ces pilotes et sources de données ne restaurent pas réellement les transactions quand elles sont demandées.
État suspendu
Dans les gestionnaires de pilotes qui ont été publiés avant Windows 7, une transaction était active si SQLEndTran a retourné SQL_ERROR du pilote. Toutefois, il était possible que la transaction ait été validée avec succès sur le serveur, mais que le pilote sur le client n’avait pas été averti (par exemple, parce qu’une erreur réseau s’est produite). Cela laisserait la connexion dans un état incorrect. À compter de Windows 7, lorsque SQLEndTran retourne SQL_ERROR, la connexion peut être dans un état suspendu. Dans un état suspendu, il est possible d’appeler des fonctions en lecture seule. Finalement, l’application doit appeler SQLDisconnect sur une connexion suspendue pour libérer des ressources.
Si toutes les conditions suivantes sont remplies, la connexion est placée dans un état suspendu :
Le pilote retourne SQL_ERROR à partir de SQLEndTran.
Le pilote est ODBC version 3.8 ou ultérieure.
La version de l’application est 3.8 ou ultérieure ; ou l’application ODBC 2.x ou 3.x recompilée annule correctement la fonction SQLEndTran via SQLCancelHandle.
Le pilote n’a pas retourné l’un des messages suivants, ce qui confirme que la transaction n’a pas terminé :
25S03 : La transaction est restaurée
40001 : Échec de sérialisation
40002 : Contrainte d’intégrité
HYC00 : fonctionnalité facultative non implémentée
Si SQLEndTran a été appelé sur un handle d’environnement et que l’une de ses connexions répond aux conditions ci-dessus, toutes les connexions se connectant au même pilote sont placées dans l’état suspendu.
Une fois qu’une application appelle SQLDisconnect sur une connexion suspendue, la connexion peut être utilisée pour se reconnecter à une autre source de données ou à la même source de données.
Fonctions connexes
| Pour plus d’informations sur | Consultez |
|---|---|
| Annulation d’une fonction s’exécutant de manière asynchrone sur un handle de connexion. | SQLCancelHandle, fonction |
| Retour d’informations sur un pilote ou une source de données | SQLGetInfo, fonction |
| Libération d’un handle | SQLFreeHandle, fonction |
| Libération d’un handle d’instruction | SQLFreeStmt, 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)