Fonction SQLEndTran

  • Article

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.

Notes

Pour plus d’informations sur ce à quoi le Gestionnaire de pilotes mappe cette fonction quand odbc 3. L’application x fonctionne avec odbc 2. Pilote x , consultez Mappage des fonctions de remplacement pour la compatibilité descendante des applications.

Syntaxe

  
SQLRETURN SQLEndTran(  
     SQLSMALLINT   HandleType,  
     SQLHANDLE     Handle,  
     SQLSMALLINT   CompletionType);

Arguments

HandleType
[Entrée] Identificateur de type de handle. Contient SQL_HANDLE_ENV (si Handle est un handle d’environnement) ou SQL_HANDLE_DBC (si Handle est un handle de connexion).

Handle
[Entrée] Handle, du type indiqué par HandleType, indiquant l’étendue de la transaction. Pour plus d’informations, consultez « Commentaires ».

CompletionType
[Entrée] L’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 le 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 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.)
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 il n’est pas possible de déterminer si le COMMIT ou ROLLBACK demandé s’est produit avant l’échec.
25S01 État de la transaction inconnu Une ou plusieurs des 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 été en mesure de garantir que tout le travail de la transaction globale pouvait être effectué atomiquement, et la transaction est toujours active.
25S03 La transaction est restaurée Le pilote n’a pas été en mesure de garantir que tout le travail de la transaction globale pouvait être effectué de manière atomique et que tout le travail de la transaction active dans Handle a été restauré.
40001 Échec de sérialisation La transaction a été annulé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é annulée.
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 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 la 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 la fin de l’exécution de la fonction SQLCancelHandle , elle a été appelée sur connectionHandle. Ensuite, la fonction a été appelée à nouveau sur connectionHandle.

La fonction a été appelée et, avant la fin de l’exécution de SQLCancelHandle , elle a été appelée sur connectionHandle à partir d’un thread différent dans une application multithread.
HY010 Erreur de séquence de fonction (DM) Une fonction d’exécution asynchrone a été appelée pour un handle d’instruction associé à ConnectionHandle et s’exécutait toujours lorsque SQLEndTran a été appelé.

(DM) Une fonction 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 l’envoi des données pour toutes les colonnes ou paramètres de données au moment de l’exécution.

(DM) Une fonction en cours d’exécution asynchrone (et non celle-ci) a été appelée pour handle avecHandleType défini sur SQL_HANDLE_DBC et s’exécutait toujours lorsque cette fonction a été appelée.

(DM) SQLExecute, SQLExecDirect ou SQLMoreResults a été appelé pour l’un des descripteurs d’instruction associés à Handle 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 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, peut-être 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 asynchrone de la fonction 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é 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é à 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 effectuer 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 le post-traitement et terminer l’opération.

Commentaires

Pour une instance ODBC 3. Pilote x , si HandleType est SQL_HANDLE_ENV et Handle est un handle d’environnement valide, le Gestionnaire de pilotes appelleRA SQLEndTran dans chaque pilote associé à l’environnement. L’argument Handle pour l’appel à un pilote sera le handle d’environnement du pilote. Pour un ODBC 2. Pilote x , 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 sont dans un état connecté sur cet environnement. Les connexions qui ne sont pas actives n’affectent pas la transaction.

Notes

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 des 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.

Notes

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 une 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 une 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 Validation et restauration de 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 Mode de 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 et l’article 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 toute 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 toute instruction présente dans un état préparé ; l’application peut appeler SQLExecute pour une instruction associée à la connexion sans appeler d’abord 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 sur la ligne vers laquelle ils ont pointé 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 renvoie SQL_SUCCESS (indiquant qu’il n’y a aucun travail à commiter ou à récupérer) 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’il soit appelé avec un CompletionType de SQL_COMMIT ou SQL_ROLLBACK.

Les pilotes ou les sources de données qui ne prennent pas en charge les transactions (l’optionSQLGetInfo SQL_TXN_CAPABLE est SQL_TC_NONE) sont en fait toujours en mode de validation automatique et retournent donc toujours des SQL_SUCCESS pour SQLEndTran, qu’ils soient appelés ou non avec un CompletionType de SQL_COMMIT ou SQL_ROLLBACK. Ces pilotes et sources de données ne restaurent pas réellement les transactions lorsqu’elles sont demandées.

État suspendu

Dans les gestionnaires de pilotes publiés avant Windows 7, une transaction était active si SQLEndTran renvoyait 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’ait pas été averti (par exemple, en raison d’une erreur réseau). 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 suspendue :

  • 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, qui confirment que la transaction n’est pas terminée :

    • 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 remplit les conditions ci-dessus, toutes les connexions se connectant au même pilote sont mises à l’état suspendu.

Une fois qu’une application a appelé 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.

Pour obtenir des informations sur Consultez
Annulation d’une fonction exécutée de façon asynchrone sur un handle de connexion. SQLCancelHandle, fonction
Retour d’informations sur un pilote ou une source de données Fonction SQLGetInfo
Libération d’un handle Fonction SQLFreeHandle
Libération d’un handle d’instruction Fonction SQLFreeStmt

Voir aussi

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