Fonction SQLFreeHandle

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

Résumé
SQLFreeHandle libère les ressources associées à un environnement, une connexion, une instruction ou un handle descripteur spécifique.

Notes

Cette fonction est une fonction générique pour libérer des handles. Il remplace les fonctions ODBC 2.0 SQLFreeConnect (pour libérer un handle de connexion) et SQLFreeEnv (pour libérer un handle d’environnement). SQLFreeConnect et SQLFreeEnv sont tous deux dépréciés dans ODBC 3*.x*. SQLFreeHandle remplace également la fonction ODBC 2.0 SQLFreeStmt (par l’option SQL_DROP) pour libérer un handle d’instruction. Pour plus d’informations, consultez « Commentaires ». Pour plus d’informations sur ce à quoi le Gestionnaire de pilotes mappe cette fonction lorsqu’une application ODBC 3*.x* fonctionne avec un pilote ODBC 2*.x*, consultez Mappage des fonctions de remplacement pour la compatibilité descendante des applications.

Syntaxe

  
SQLRETURN SQLFreeHandle(  
     SQLSMALLINT   HandleType,  
     SQLHANDLE     Handle);  

Arguments

HandleType
[Entrée] Type de handle à libérer par SQLFreeHandle. Il doit s’agir de l’une des valeurs suivantes :

• SQL_HANDLE_DBC

• SQL_HANDLE_DBC_INFO_TOKEN

• SQL_HANDLE_DESC

• SQL_HANDLE_ENV

• SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN handle est utilisé uniquement par le gestionnaire de pilotes et le pilote. Les applications ne doivent pas utiliser ce type de handle. Pour plus d’informations sur SQL_HANDLE_DBC_INFO_TOKEN, consultez Développement de la sensibilisation Connection-Pool dans un pilote ODBC.

Si HandleType n’est pas l’une de ces valeurs, SQLFreeHandle retourne SQL_INVALID_HANDLE.

Handle
[Entrée] Poignée à libérer.

Retours

SQL_SUCCESS, SQL_ERROR ou SQL_INVALID_HANDLE.

Si SQLFreeHandle retourne SQL_ERROR, le handle est toujours valide.

Diagnostics

Lorsque SQLFreeHandle retourne SQL_ERROR, une valeur SQLSTATE associée peut être obtenue à partir de la structure de données de diagnostic pour le handle que SQLFreeHandle a essayé de libérer, mais n’a pas pu. Le tableau suivant répertorie les valeurs SQLSTATE généralement retournées par SQLFreeHandle 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
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.
HY010	Erreur de séquence de fonction	(DM) L’argument HandleType a été SQL_HANDLE_ENV et au moins une connexion était dans un état alloué ou connecté. SQLDisconnect et SQLFreeHandle avec un HandleType de SQL_HANDLE_DBC doivent être appelés pour chaque connexion avant d’appeler SQLFreeHandle avec un HandleType de SQL_HANDLE_ENV. (DM) L’argument HandleType a été SQL_HANDLE_DBC et la fonction a été appelée avant d’appeler SQLDisconnect pour la connexion. (DM) L’argument HandleType a été SQL_HANDLE_DBC. Une fonction d’exécution asynchrone a été appelée avec Handle et la fonction s’exécutait toujours lorsque cette fonction a été appelée. (DM) L’argument HandleType a été SQL_HANDLE_STMT. SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos a été appelé avec le handle d’instruction et 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. (DM) L’argument HandleType a été SQL_HANDLE_STMT. Une fonction d’exécution asynchrone a été appelée sur le handle d’instruction ou sur le handle de connexion associé et la fonction s’exécutait toujours lorsque cette fonction a été appelée. (DM) L’argument HandleType a été SQL_HANDLE_DESC. 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) Tous les handles de filiales et autres ressources n’ont pas été publiés avant l’appel de SQLFreeHandle . (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_STMT ou SQL_HANDLE_DESC 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.
HY013	Erreur de gestion de la mémoire	L’argument HandleType était SQL_HANDLE_STMT ou SQL_HANDLE_DESC, et l’appel de fonction n’a pas pu être traité, car les objets de mémoire sous-jacents n’étaient pas accessibles, peut-être en raison de conditions de mémoire insuffisantes.
HY017	Utilisation non valide d’un handle de descripteur alloué automatiquement.	(DM) L’argument Handle a été défini sur le handle pour un descripteur alloué automatiquement.
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) L’argument HandleType était SQL_HANDLE_DESC et le pilote était un pilote ODBC 2*.x*. (DM) L’argument HandleType était SQL_HANDLE_STMT et le pilote n’était pas un pilote ODBC valide.

Commentaires

SQLFreeHandle est utilisé pour libérer des handles pour les environnements, les connexions, les instructions et les descripteurs, comme décrit dans les sections suivantes. Pour obtenir des informations générales sur les handles, consultez Handles.

Une application ne doit pas utiliser de handle une fois qu’elle a été libérée ; le Gestionnaire de pilotes ne vérifie pas la validité d’un handle dans un appel de fonction.

Libération d’un handle d’environnement

Avant d’appeler SQLFreeHandle avec un HandleType de SQL_HANDLE_ENV, une application doit appeler SQLFreeHandle avec un HandleType de SQL_HANDLE_DBC pour toutes les connexions allouées dans l’environnement. Sinon, l’appel à SQLFreeHandle retourne SQL_ERROR et l’environnement, et toute connexion active reste valide. Pour plus d’informations, consultez Handles d’environnement et Allocation du handle d’environnement.

Si l’environnement est un environnement partagé, l’application qui appelle SQLFreeHandle avec un HandleType de SQL_HANDLE_ENV n’a plus accès à l’environnement après l’appel, mais les ressources de l’environnement ne sont pas nécessairement libérées. L’appel à SQLFreeHandle décrémente le nombre de références de l’environnement. Le nombre de références est géré par le Gestionnaire de pilotes. S’il n’atteint pas zéro, l’environnement partagé n’est pas libéré, car il est toujours utilisé par un autre composant. Si le nombre de références atteint zéro, les ressources de l’environnement partagé sont libérées.

Libération d’un handle de connexion

Avant d’appeler SQLFreeHandle avec un HandleType de SQL_HANDLE_DBC, une application doit appeler SQLDisconnect pour la connexion s’il existe une connexion sur ce handle** Sinon, l’appel à SQLFreeHandle retourne SQL_ERROR et la connexion reste valide.

Pour plus d’informations, consultez Handles de connexion et Déconnexion d’une source de données ou d’un pilote.

Libération d'un descripteur d'instruction

Un appel à SQLFreeHandle avec un HandleType de SQL_HANDLE_STMT libère toutes les ressources qui ont été allouées par un appel à SQLAllocHandle avec un HandleType de SQL_HANDLE_STMT. Lorsqu’une application appelle SQLFreeHandle pour libérer une instruction dont les résultats sont en attente, les résultats en attente sont supprimés. Lorsqu’une application libère un handle d’instruction, le pilote libère les quatre descripteurs alloués automatiquement associés à ce handle. Pour plus d’informations, consultez Descripteurs d’instruction et Libération d’un handle d’instruction.

Notez que SQLDisconnect supprime automatiquement toutes les instructions et descripteurs ouverts sur la connexion.

Libération d’un handle de descripteur

Un appel à SQLFreeHandle avec un HandleType de SQL_HANDLE_DESC libère le handle de descripteur dans Handle. L’appel à SQLFreeHandle ne libère aucune mémoire allouée par l’application qui peut être référencée par un champ pointeur (y compris SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR et SQL_DESC_OCTET_LENGTH_PTR) d’un enregistrement de descripteur handle. La mémoire allouée par le pilote pour les champs qui ne sont pas des champs pointeurs est libérée lorsque le handle est libéré. Lorsqu’un handle de descripteur alloué par l’utilisateur est libéré, toutes les instructions auxquelles le handle libéré avait été associé reviennent à leurs handles de descripteurs alloués automatiquement.

Notes

Les pilotes ODBC 2*.x* ne prennent pas en charge la libération des handles de descripteurs, tout comme ils ne prennent pas en charge l’allocation de handles de descripteur.

Notez que SQLDisconnect supprime automatiquement toutes les instructions et descripteurs ouverts sur la connexion. Lorsqu’une application libère un handle d’instruction, le pilote libère tous les descripteurs générés automatiquement associés à ce handle.

Pour plus d’informations sur les descripteurs, consultez Descripteurs.

Exemple de code

Pour obtenir des exemples de code supplémentaires, consultez SQLBrowseConnect et SQLConnect.

Code

// SQLFreeHandle.cpp  
// compile with: user32.lib odbc32.lib  
#include <windows.h>  
#include <sqlext.h>  
#include <stdio.h>  
  
int main() {  
   SQLRETURN retCode;  
   HWND desktopHandle = GetDesktopWindow();   // desktop's window handle  
   SQLCHAR connStrbuffer[1024];  
   SQLSMALLINT connStrBufferLen;  
  
   // Initialize the environment, connection, statement handles.  
   SQLHENV henv = NULL;   // Environment     
   SQLHDBC hdbc = NULL;   // Connection handle  
   SQLHSTMT hstmt = NULL;   // Statement handle  
  
   // Allocate the environment.  
   retCode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
  
   // Set environment attributes.  
   retCode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, -1);  
  
   // Allocate the connection.  
   retCode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
  
   // Set the login timeout.  
   retCode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)10, 0);  
  
   // Let the user select the data source and connect to the database.  
   retCode = SQLDriverConnect(hdbc, desktopHandle, (SQLCHAR *)"Driver={SQL Server}", SQL_NTS, connStrbuffer, 1025, &connStrBufferLen, SQL_DRIVER_PROMPT);  
  
   retCode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
   // Free handles, and disconnect.     
   if (hstmt) {   
      SQLFreeHandle(SQL_HANDLE_STMT, hstmt);  
      hstmt = NULL;   
   }  
   if (hdbc) {   
      SQLDisconnect(hdbc);  
      SQLFreeHandle(SQL_HANDLE_DBC, hdbc);  
      hdbc = NULL;   
   }  
   if (henv) {   
      SQLFreeHandle(SQL_HANDLE_ENV, henv);  
      henv = NULL;   
   }  
}  

Fonctions connexes

Pour obtenir des informations sur	Consultez
Allocation d’un handle	SQLAllocHandle, fonction
Annulation du traitement des instructions	SQLCance Functionl
Définition d’un nom de curseur	SQLSetCursorName, fonction

Voir aussi

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