Fonction SQLFreeStmt

  • Article

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);  
}
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