Condividi tramite

SQLFreeStmt Function

  • Articolo

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.

SQLSTATE Errore Descrizione
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 è stato chiamato SQLFreeStmt .

(DM) SQLExecute, SQLExecDirect o SQLMoreResults è stato chiamato per StatementHandle e restituito SQL_PARAM_DATA_AVAILABLE. Questa funzione è stata chiamata con Option impostata su SQL_RESET_PARAMS prima del recupero dei dati per tutti i parametri trasmessi.

(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 non compreso nell'intervallo (DM) Il valore specificato per l'argomento Option 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.

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);  
}
Per informazioni su Vedere
Allocazione di un handle Funzione SQLAllocHandle
Annullamento dell'elaborazione delle istruzioni Funzione SQLCancel
Chiusura di un cursore Funzione SQLCloseCursor
Liberare un handle Funzione SQLFreeHandle
Impostazione di un nome di cursore Funzione SQLSetCursorName

Vedi anche

Riferimento API ODBC
File di intestazione ODBC