SQLFreeStmt-funktion

Överensstämmelse
Version introducerad: ODBC 1.0 Standardefterlevnad: ISO 92

Summary
SQLFreeStmt slutar behandla ett specifikt uttalande, stänger alla öppna markörer kopplade till satsen, kasserar väntande resultat eller, valfritt, frigör alla resurser kopplade till satshandtaget.

Syntax

  
SQLRETURN SQLFreeStmt(  
     SQLHSTMT       StatementHandle,  
     SQLUSMALLINT   Option);  

Arguments

StatementHandle
[Input] Satshandtag

Alternativ
[Input] Ett av följande alternativ:

SQL_ STÄNG: Stänger markören kopplad till StatementHandle (om en sådan definierades) och kasserar alla väntande resultat. Applikationen kan öppna denna markör igen senare genom att köra en SELECT-sats igen med samma eller olika parametervärden. Om ingen markör är öppen har detta alternativ ingen effekt på applikationen. SQLCloseCursor kan också anropas för att stänga en markör. För mer information, se Stänga markören.

SQL_DROP: Detta alternativ är föråldrat. Ett anrop till SQLFreeStmt med ett alternativ SQL_DROP mappas i Driver Manager till SQLFreeHandle.

SQL_UNBIND: Sätter fältet SQL_DESC_COUNT i ARD till 0 och släpper alla kolumnbuffertar begränsade av SQLBindCol för den givna StatementHandle. Detta avbinder inte bokmärkeskolumnen; för att göra det sätts SQL_DESC_DATA_PTR fältet i ARD för bokmärkeskolumnen till NULL. Observera att om denna operation utförs på en explicit tilldelad deskriptor som delas av mer än ett sats, kommer operationen att påverka bindningarna för alla satser som delar deskriptorn. För mer information, se Översikt över att hämta resultat (Basic).

SQL_RESET_PARAMS: Sätter APD:ns SQL_DESC_COUNT fält till 0 och släpper alla parameterbuffertar som SQLBindParameter för det givna StatementHandle. Om denna operation utförs på en explicit allokerad deskriptor som delas av mer än ett sats, kommer denna operation att påverka bindningarna för alla satser som delar deskriptorn. För mer information, se Bindningsparametrar.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR eller SQL_INVALID_HANDLE.

Diagnostics

När SQLFreeStmt returnerar SQL_ERROR eller SQL_SUCCESS_WITH_INFO kan ett associerat SQLSTATE-värde erhållas genom att anropa SQLGetDiagRec med en HandleType av SQL_HANDLE_STMT och ett Handle av StatementHandle. Följande tabell listar de SQLSTATE-värden som vanligtvis returneras av SQLFreeStmt och förklarar var och en i kontexten av denna funktion; notationen "(DM)" föregår beskrivningarna av SQLSTATE som returneras av Driver Manager. Returkoden som är associerad med varje SQLSTATE-värde är SQL_ERROR, om inget annat anges.

Comments

Att anropa SQLFreeStmt med SQL_CLOSE-alternativet är likvärdigt med att anropa SQLCloseCursor, förutom att SQLFreeStmt med SQL_CLOSE inte påverkar applikationen om ingen markör är öppen på satsen. Om ingen markör är öppen returnerar ett anrop till SQLCloseCursor SQLSTATE 24000 (Ogiltigt markörtillstånd).

Ett program bör inte använda ett statement-handtag efter att det har frigjorts; Driver Manager kontrollerar inte giltigheten av ett handtag i ett funktionsanrop.

Example

Det är en bra programmeringsmetod att fria handtag. För enkelhetens skull inkluderar dock följande exempel inte kod som frigör tilldelade handtag. För ett exempel på hur man frigör handtag, se 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);  
}  

Relaterade funktioner

Relaterat innehåll

• ODBC API-referens
• ODBC-huvudfiler