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.
| 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);
}
Funzioni correlate
| 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
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per