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