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.

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

Voir aussi

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