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.

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

Funzioni correlate

Contenuti correlati

• Riferimento API ODBC
• File di intestazione ODBC