SQLDisconnect, fonction

Conformité
Version introduite : Conformité aux normes ODBC 1.0 : ISO 92

Résumé
SQLDisconnect ferme la connexion associée à un handle de connexion spécifique.

Syntaxe

  
SQLRETURN SQLDisconnect(  
     SQLHDBC     ConnectionHandle);  

Arguments

ConnectionHandle
[Entrée] Handle de connexion.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE ou SQL_STILL_EXECUTING.

Diagnostics

Lorsque SQLDisconnect 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_DBC et un handlede ConnectionHandle. Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLDisconnect 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.)
01002	Erreur de déconnexion	Une erreur s’est produite pendant la déconnexion. Toutefois, la déconnexion a réussi. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
08003	Connexion non ouverte	(DM) La connexion spécifiée dans l’argument ConnectionHandle n’a pas été ouverte.
25000	État de transaction non valide	Une transaction a été en cours sur la connexion spécifiée par l’argument ConnectionHandle. La transaction reste active.
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 *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.
HY008	Opération annulée	Le traitement asynchrone a été activé pour connectionHandle. La fonction a été appelée et, avant qu’elle ne finhed, 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 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 en cours d’exécution asynchrone a été appelée pour un InstructionHandle associé à ConnectionHandle et s’exécutait toujours lorsque SQLDisconnect 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 InstructionHandle associé à ConnectionHandle et a renvoyé 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.
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.
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 ne réponde à la demande, et la connexion est toujours active. 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

Si une application appelle SQLDisconnect après que SQLBrowseConnect a retourné SQL_NEED_DATA et avant qu’elle ne retourne un code de retour différent, le pilote annule le processus de navigation de connexion et retourne la connexion à un état non connecté.

Si une application appelle SQLDisconnect alors qu’une transaction incomplète est associée au handle de connexion, le pilote retourne SQLSTATE 25000 (état de transaction non valide), indiquant que la transaction est inchangée et que la connexion est ouverte. Une transaction incomplète est une transaction qui n’a pas été validée ou restaurée avec SQLEndTran.

Si une application appelle SQLDisconnect avant d’avoir libéré toutes les instructions associées à la connexion, le pilote, après s’être déconnecté de la source de données, libère ces instructions et tous les descripteurs qui ont été explicitement alloués sur la connexion. Toutefois, si une ou plusieurs des instructions associées à la connexion sont toujours en cours d’exécution asynchrone, SQLDisconnect retourne SQL_ERROR avec la valeur SQLSTATE HY010 (erreur de séquence de fonction). En outre, SQLDisconnect libère toutes les instructions associées et tous les descripteurs qui ont été explicitement alloués sur la connexion, si la connexion est dans un état suspendu ou si SQLDisconnect a été correctement annulé par SQLCancelHandle.

Pour plus d’informations sur la façon dont une application utilise SQLDisconnect, consultez Déconnexion d’une source de données ou d’un pilote.

Déconnexion d’une connexion groupée

Si le regroupement de connexions est activé pour un environnement partagé et qu’une application appelle SQLDisconnect sur une connexion dans cet environnement, la connexion est retournée au pool de connexions et est toujours disponible pour d’autres composants utilisant le même environnement partagé.

Exemple de code

Consultez Exemple de programme ODBC, fonction SQLBrowseConnect et fonction SQLConnect.

Fonctions connexes

Pour obtenir des informations sur	Consultez
Allocation d’un handle	SQLAllocHandle, fonction
Connexion à une source de données	SQLConnect, fonction
Connexion à une source de données à l’aide d’une chaîne de connexion ou d’une boîte de dialogue	SQLDriverConnect, fonction
Exécution d’une opération de validation ou de restauration	Fonction SQLEndTran
Libération d’un handle de connexion	SQLFreeConnect, fonction

Voir aussi

Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC