Funzione SQLFreeStmt

Conformità
Versione introdotta: Conformità agli standard ODBC 1.0: ISO 92

Sommario
SQLFreeStmt interrompe l'elaborazione associata a una specifica istruzione, chiude tutti i cursori aperti associati all'istruzione, scarta i risultati in attesa o, opzionalmente, libera tutte le risorse associate all'handle dell'istruzione.

Sintassi

  
SQLRETURN SQLFreeStmt(  
     SQLHSTMT       StatementHandle,  
     SQLUSMALLINT   Option);

Arguments

StatementHandle
[Input] Manico di istruzione

Opzione
[Input] Una delle seguenti opzioni:

SQL_ CLOSE: Chiude il cursore associato a StatementHandle (se ne era definito) e scarta tutti i risultati in sospeso. L'applicazione può riaprire questo cursore successivamente eseguendo nuovamente un'istruzione SELECT con gli stessi o diversi valori di parametro. Se nessun cursore è aperto, questa opzione non ha effetto sull'applicazione. SQLCloseCursor può anche essere chiamato per chiudere un cursore. Per maggiori informazioni, vedi Chiusura del Cursore.

SQL_DROP: Questa opzione è deprecata. Una chiamata a SQLFreeStmt con l'opzione di SQL_DROP viene mappata nel Driver Manager su SQLFreeHandle.

SQL_UNBIND: Imposta il campo SQL_DESC_COUNT dell'ARD a 0, rilasciando tutti i buffer di colonna vincolati da SQLBindCol per il StatementHandle assegnato. Questo non libera la colonna dei segnalibri; per farlo, il campo SQL_DESC_DATA_PTR dell'ARD per la colonna dei segnalibri viene impostato su NULL. Si noti che se questa operazione viene eseguita su un descrittore esplicitamente allocato condiviso da più di una istruzione, l'operazione influenzerà i binding di tutte le istruzioni che condividono il descrittore. Per maggiori informazioni, vedi Panoramica del recupero dei risultati (Base).

SQL_RESET_PARAMS: Imposta il campo SQL_DESC_COUNT dell'APD a 0, rilasciando tutti i buffer di parametri impostati da SQLBindParameter per il StatementHandle assegnato. Se questa operazione viene eseguita su un descrittore esplicitamente allocato condiviso da più di una istruzione, questa operazione influenzerà le associazioni di tutte le istruzioni che condividono il descrittore. Per maggiori informazioni, vedi Parametri di legame.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnostica

Quando SQLFreeStmt restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, un valore SQLSTATE associato può essere ottenuto chiamando SQLGetDiagRec con un HandleType di SQL_HANDLE_STMT e un Handle di StatementHandle. La tabella seguente elenca i valori di SQLSTATE tipicamente restituiti da SQLFreeStmt e li spiega nel contesto di questa funzione; la notazione "(DM)" precede le descrizioni degli stati SQL restituite dal Driver Manager. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.

SQLSTATE	Error	Description
01000	Avviso generale	Messaggio informativo specifico del driver. (La funzione restituisce SQL_SUCCESS_WITH_INFO.
HY000	Errore generale	Si è verificato un errore per il quale non è stato specificato SQLSTATE e per il quale non è stato definito alcun SQLSTATE specifico dell'implementazione. Il messaggio di errore restituito da SQLGetDiagRec nel buffer MessageText* descrive l'errore e la relativa causa.
HY001	Errore di allocazione della memoria	Il driver non è riuscito ad allocare memoria necessaria per supportare l'esecuzione o il completamento della funzione.
HY010	Errore della sequenza di funzioni	(DM) È stata chiamata una funzione in esecuzione asincrona per l'handle di connessione associato a StatementHandle. Questa funzione asincrona era ancora in esecuzione quando veniva chiamato SQLFreeStmt . (DM) SQLExecute, SQLExecDirect o SQLMoreResults è stato chiamato per StatementHandle e restituito SQL_PARAM_DATA_AVAILABLE. Questa funzione veniva chiamata con Option impostata su SQL_RESET_PARAMS prima che i dati venissero recuperati per tutti i parametri in streaming. (DM) È stata chiamata una funzione in esecuzione asincrona per StatementHandle ed era ancora in esecuzione quando questa funzione è stata chiamata. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos è stato chiamato per StatementHandle e restituito SQL_NEED_DATA. Questa funzione è stata chiamata prima dell'invio dei dati per tutti i parametri o le colonne data-at-execution.
HY013	Errore di gestione della memoria	Impossibile elaborare la chiamata di funzione perché non è stato possibile accedere agli oggetti di memoria sottostanti, probabilmente a causa di condizioni di memoria insufficiente.
HY092	Tipo di opzione fuori portata	(DM) Il valore specificato per l'argomento Opzione non era: SQL_CLOSE SQL_DROP SQL_UNBIND SQL_RESET_PARAMS
HYT01	Il timeout della connessione è scaduto	Periodo di timeout della connessione scaduto prima che l'origine dati rispondesse alla richiesta. Il periodo di timeout della connessione viene impostato tramite SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Il driver non supporta questa funzione	(DM) Il driver associato a StatementHandle non supporta la funzione.

Comments

Chiamare SQLFreeStmt con l'opzione SQL_CLOSE è equivalente a chiamare SQLCloseCursor, tranne che SQLFreeStmt con SQL_CLOSE non influisce sull'applicazione se non è aperto alcun cursore sull'istruzione. Se nessun cursore è aperto, una chiamata a SQLCloseCursor restituisce SQLSTATE 24000 (stato del cursore non valido).

Un'applicazione non dovrebbe utilizzare un handle di istruzione dopo essere stato liberato; il Driver Manager non verifica la validità di un handle in una chiamata di funzione.

Example

È una buona pratica di programmazione liberare handle. Tuttavia, per semplicità, il seguente esempio non include il codice che libera gli handle assegnati. Per un esempio di come liberare handle, vedi SQLFreeHandle Function.

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

Per informazioni su	Vedi
Allocazione di un manico	Funzione SQLAllocHandle
Annullamento dell'elaborazione delle istruzioni	Funzione SQLCancel
Chiusura di un cursore	Funzione SQLCloseCursor
Liberare una maniglia	Funzione SQLFreeHandle
Impostazione di un nome di cursore	Funzione SQLSetCursorName

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-08-24