SQLFreeHandle, fonction

Article
12/19/2024

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

résumé
SQLFreeHandle libère des ressources associées à un handle d’environnement, de connexion, d’instruction ou de descripteur spécifique.

Note

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 dépréciés dans ODBC 3*.x*. SQLFreeHandle remplace également la fonction ODBC 2.0 SQLFreeStmt (par l’SQL_DROP Option) pour libérer un handle d’instruction. Pour plus d’informations, consultez « Commentaires ». Pour plus d’informations sur ce que le Gestionnaire de pilotes mappe cette fonction lorsqu’une application ODBC 3*.x* fonctionne avec un pilote ODBC 2*.x*, consultez fonctions de remplacement de mappage pour la compatibilité descendante des applications.

Syntaxe

  
SQLRETURN SQLFreeHandle(  
     SQLSMALLINT   HandleType,  
     SQLHANDLE     Handle);

Arguments

HandleType
[Entrée] Type de handle à libérer par SQLFreeHandle. Doit être 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 Connection-Pool awareness dans unde pilote ODBC.

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

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

Retourne

SQL_SUCCESS, SQL_ERROR ou SQL_INVALID_HANDLE.

Si SQLFreeHandle retourne SQL_ERROR, le handle est toujours valide.

Diagnostic

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 SQLFreeHandle essayé de libérer, mais pas. 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 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
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 *MessageText 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.
HY010	Erreur de séquence de fonction	(DM) L’argument handleType était 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 doit être appelé 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 était SQL_HANDLE_DBC. Une fonction en cours d’exécution asynchrone a été appelée avec Handle et la fonction était toujours en cours d’exécution lors de l’appel de cette fonction. (DM) L’argument de HandleType était SQL_HANDLE_STMT. SQLExecute, SQLExecDirect, SQLBulkOperationsou SQLSetPos a été appelé avec le handle d’instruction 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) L’argument de HandleType était SQL_HANDLE_STMT. Une fonction en cours d’exécution asynchrone a été appelée sur le handle d’instruction ou sur le handle de connexion associé et la fonction était toujours en cours d’exécution lorsque cette fonction a été appelée. (DM) L’argument de HandleType était SQL_HANDLE_DESC. Une fonction en cours 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 SQLFreeHandle a été appelé. (DM) SQLExecute, SQLExecDirectou SQLMoreResults a été appelé pour l’un des handles d’instruction associés au handle de handle HandleType et HandleType 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 en continu.
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’ont pas pu être accessibles, éventuellement en raison de conditions de mémoire insuffisantes.
HY017	Utilisation non valide d’un handle de descripteur alloué automatiquement.	(DM) L’argument de 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	Expiration du délai d’expiration de la connexion	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 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 un 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 sous 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 conservé 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’unde pilote .

Libération d’un handle d’instruction

Un appel à SQLFreeHandle avec un HandleType de SQL_HANDLE_STMT libère toutes les ressources allouées par un appel à SQLAllocHandle avec un HandleType de SQL_HANDLE_STMT. Lorsqu’une application appelle SQLFreeHandle pour libérer une instruction qui a des résultats 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 Handles d’instruction et libérer 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 de pointeur (y compris SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR et SQL_DESC_OCTET_LENGTH_PTR) d’un enregistrement de descripteur de 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 descripteur alloué par l’utilisateur est libéré, toutes les instructions auxquelles le handle libéré avait été associé à la restauration de leurs handles de descripteur alloués automatiquement respectivement.

Note

Les pilotes ODBC 2*.x* ne prennent pas en charge la libération des handles de descripteur, 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;   
   }  
}

Pour plus d’informations sur	Voir
Allocation d’un handle	fonction SQLAllocHandle
Annulation du traitement des instructions	fonction SQLCancel
Définition d’un nom de curseur	fonction SQLSetCursorName

Voir aussi

informations de référence sur l’API ODBC
fichiers d’en-tête ODBC
exemple de programme ODBC

Partager via

SQLFreeHandle, fonction

Syntaxe

Arguments

Retourne

Diagnostic

Commentaires

Libération d’un handle d’environnement

Libération d’un handle de connexion

Libération d’un handle d’instruction

Libération d’un handle de descripteur

Exemple de code

Code

Voir aussi

Commentaires

Ressources supplémentaires

Partager via

SQLFreeHandle, fonction

Syntaxe

Arguments

Retourne

Diagnostic

Commentaires

Libération d’un handle d’environnement

Libération d’un handle de connexion

Libération d’un handle d’instruction

Libération d’un handle de descripteur

Exemple de code

Code

Fonctions associées

Voir aussi

Commentaires

Ressources supplémentaires