Fonction SQLFreeStmt
Conformité
Version introduite : Conformité aux normes ODBC 1.0 : ISO 92
Résumé
SQLFreeStmt arrête le traitement associé à une instruction spécifique, ferme tous les curseurs ouverts associés à l’instruction, ignore les résultats en attente ou, éventuellement, libère toutes les ressources associées au handle d’instruction.
Syntaxe
SQLRETURN SQLFreeStmt(
SQLHSTMT StatementHandle,
SQLUSMALLINT Option);
Arguments
StatementHandle
[Entrée] Handle d’instruction
Option
[Entrée] Une des options suivantes :
SQL_ CLOSE : ferme le curseur associé à StatementHandle (le cas échéant) et ignore tous les résultats en attente. L’application peut rouvrir ce curseur ultérieurement en réécutant une instruction SELECT avec les valeurs de paramètre identiques ou différentes. Si aucun curseur n’est ouvert, cette option n’a aucun effet pour l’application. SQLCloseCursor peut également être appelé pour fermer un curseur. Pour plus d’informations, consultez Fermeture du curseur.
SQL_DROP : cette option est déconseillée. Un appel à SQLFreeStmt avec une option de SQL_DROP est mappé dans le Gestionnaire de pilotes à SQLFreeHandle.
SQL_UNBIND : définit le champ SQL_DESC_COUNT de l’ARD sur 0, libérant toutes les mémoires tampons de colonne liées par SQLBindCol pour l’InstructionHandle donnée. Cela n’annule pas la liaison de la colonne signet ; pour ce faire, le champ SQL_DESC_DATA_PTR de l’ARD pour la colonne signet est défini sur NULL. Notez que si cette opération est effectuée sur un descripteur explicitement alloué qui est partagé par plusieurs instructions, l’opération affecte les liaisons de toutes les instructions qui partagent le descripteur. Pour plus d’informations, consultez Vue d’ensemble de la récupération des résultats (de base).
SQL_RESET_PARAMS : définit le champ SQL_DESC_COUNT de l’APD sur 0, en libérant tous les tampons de paramètres définis par SQLBindParameter pour l’InstructionHandle donnée. Si cette opération est effectuée sur un descripteur explicitement alloué qui est partagé par plusieurs instructions, cette opération affecte les liaisons de toutes les instructions qui partagent le descripteur. Pour plus d’informations, consultez Paramètres de liaison.
Retours
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnostics
Lorsque SQLFreeStmt 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_STMT et un Handle of StatementHandle. Le tableau suivant répertorie les valeurs SQLSTATE généralement retournées par SQLFreeStmt 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.) |
| 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) Une fonction d’exécution asynchrone a été appelée pour le handle de connexion associé à l’InstructionHandle. Cette fonction asynchrone était toujours en cours d’exécution lorsque SQLFreeStmt a été appelé. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults a été appelé pour l’instruction StatementHandle et a retourné SQL_PARAM_DATA_AVAILABLE. Cette fonction a été appelée avec option définie sur SQL_RESET_PARAMS avant la récupération des données pour tous les paramètres diffusés. (DM) Une fonction d’exécution asynchrone a été appelée pour l’InstructionHandle 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 l’InstructionHandle 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 consultés, peut-être en raison de conditions de mémoire insuffisantes. |
| HY092 | Type d’option hors plage | (DM) La valeur spécifiée pour l’argument Option n’était pas : SQL_CLOSE SQL_DROP SQL_UNBIND SQL_RESET_PARAMS |
| 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) Le pilote associé à l’InstructionHandle ne prend pas en charge la fonction. |
Commentaires
Appeler SQLFreeStmt avec l’option SQL_CLOSE équivaut à appeler SQLCloseCursor, sauf que SQLFreeStmt avec SQL_CLOSE n’affecte pas l’application si aucun curseur n’est ouvert sur l’instruction. Si aucun curseur n’est ouvert, un appel à SQLCloseCursor renvoie SQLSTATE 24000 (état de curseur non valide).
Une application ne doit pas utiliser de handle d’instruction 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.
Exemple
Il s’agit d’une bonne pratique de programmation pour les handles gratuits. Toutefois, par souci de simplicité, l’exemple suivant n’inclut pas de code qui libère les handles alloués. Pour obtenir un exemple montrant comment libérer des handles, consultez FONCTION SQLFreeHandle.
// SQLFreeStmt.cpp
// compile with: user32.lib odbc32.lib
#include <windows.h>
#include <sqlext.h>
int main() {
// declare and initialize the environment, connection, statement handles
SQLHENV henv = NULL; // Environment
SQLHDBC hdbc = NULL; // Connection handle
SQLHSTMT hstmt = NULL; // Statement handle
SQLRETURN retCode;
HWND desktopHandle = GetDesktopWindow(); // desktop's window handle
SQLCHAR connStrbuffer[1024];
SQLSMALLINT connStrBufferLen;
retCode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
retCode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, -1);
retCode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);
retCode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)10, 0);
retCode = SQLDriverConnect(hdbc, desktopHandle, (SQLCHAR *)"Driver={SQL Server}", SQL_NTS, connStrbuffer, 1024 + 1, &connStrBufferLen, SQL_DRIVER_PROMPT);
retCode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
retCode = SQLFreeStmt(hstmt, SQL_CLOSE);
retCode = SQLFreeStmt(hstmt, SQL_UNBIND);
retCode = SQLFreeStmt(hstmt, SQL_RESET_PARAMS);
}
Fonctions connexes
| Pour obtenir des informations sur | Consultez |
|---|---|
| Allocation d’un handle | SQLAllocHandle, fonction |
| Annulation du traitement des instructions | SQLCancel, fonction |
| Fermeture d’un curseur | SQLCloseCursor, fonction |
| Libération d’un handle | Fonction SQLFreeHandle |
| 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