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.

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.

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.

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

Voir aussi

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