SQLFreeStmt Function

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

Riepilogo
SQLFreeStmt interrompe l'elaborazione associata a un'istruzione specifica, chiude tutti i cursori aperti associati all'istruzione, rimuove i risultati in sospeso o, facoltativamente, libera tutte le risorse associate all'handle di istruzione.

Sintassi

  
SQLRETURN SQLFreeStmt(  
     SQLHSTMT       StatementHandle,  
     SQLUSMALLINT   Option);  

Argomenti

StatementHandle
[Input] Handle di istruzione

Opzione
[Input] Una delle opzioni seguenti:

SQL_ CLOSE: chiude il cursore associato a StatementHandle (se definito) e rimuove tutti i risultati in sospeso. L'applicazione può riaprire questo cursore in un secondo momento eseguendo di nuovo un'istruzione SELECT con gli stessi valori di parametro o diversi. Se non è aperto alcun cursore, questa opzione non ha alcun effetto per l'applicazione. È anche possibile chiamare SQLCloseCursor per chiudere un cursore. Per altre informazioni, vedere Chiusura del cursore.

SQL_DROP: questa opzione è deprecata. Viene eseguito il mapping di una chiamata a SQLFreeStmt con un'opzionedi SQL_DROP in Gestione driver a SQLFreeHandle.

SQL_UNBIND: imposta il campo SQL_DESC_COUNT della ARD su 0, rilasciando tutti i buffer di colonna associati da SQLBindCol per l'istruzione StatementHandle specificata. Questa operazione non comporta l'associazione della colonna del segnalibro; a tale scopo, il campo SQL_DESC_DATA_PTR della ARD per la colonna del segnalibro è impostato su NULL. Si noti che se questa operazione viene eseguita su un descrittore allocato in modo esplicito condiviso da più istruzioni, l'operazione influirà sulle associazioni di tutte le istruzioni che condividono il descrittore. Per altre informazioni, vedere Panoramica del recupero dei risultati (di base).

SQL_RESET_PARAMS: imposta il campo SQL_DESC_COUNT di APD su 0, rilasciando tutti i buffer dei parametri impostati da SQLBindParameter per l'istruzione StatementHandle specificata. Se questa operazione viene eseguita su un descrittore allocato in modo esplicito condiviso da più istruzioni, questa operazione influirà sulle associazioni di tutte le istruzioni che condividono il descrittore. Per altre informazioni, vedere Parametri di associazione.

Resi

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnostica

Quando SQLFreeStmt restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con handleTypedi SQL_HANDLE_STMT e handle di StatementHandle. La tabella seguente elenca i valori SQLSTATE restituiti in genere da SQLFreeStmt e ne spiega ognuno nel contesto di questa funzione. La notazione "(DM)" precede le descrizioni di SQLSTATEs restituite da Gestione driver. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.

Commenti

La chiamata a SQLFreeStmt con l'opzione SQL_CLOSE equivale a chiamare SQLCloseCursor, ad eccezione del fatto che SQLFreeStmt con SQL_CLOSE non influisce sull'applicazione se nell'istruzione non è aperto alcun cursore. Se non è aperto alcun cursore, una chiamata a SQLCloseCursor restituisce SQLSTATE 24000 (stato cursore non valido).

Un'applicazione non deve usare un handle di istruzione dopo che è stato liberato; Gestione driver non controlla la validità di un handle in una chiamata di funzione.

Esempio

È una buona procedura di programmazione liberare handle. Tuttavia, per semplicità, l'esempio seguente non include codice che libera gli handle allocati. Per un esempio di come liberare handle, vedere Funzione 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);  
}  

Funzioni correlate

Vedi anche

Riferimento API ODBC
File di intestazione ODBC