SQLFreeHandle függvény

megfelelőségi
Bevezetett verzió: ODBC 3.0 szabványmegfelelőség: ISO 92

összefoglaló
SQLFreeHandle felszabadítja az adott környezethez, kapcsolathoz, utasításhoz vagy leíró leíróhoz társított erőforrásokat.

Jegyzet

Ez a függvény a fogópontok felszabadítására szolgáló általános függvény. Lecseréli az ODBC 2.0 függvényeket SQLFreeConnect (kapcsolati leíró felszabadítására) és SQLFreeEnv (a környezeti leírók felszabadítására). SQLFreeConnect és SQLFreeEnv az ODBC 3*.x*-ban elavultak. SQLFreeHandle az SQLFreeStmt ODBC 2.0 függvényt (a SQL_DROP beállítással) is lecseréli az utasításkezelő felszabadítására. További információ: "Megjegyzések". Ha többet szeretne tudni arról, hogy az Illesztőprogram-kezelő hogyan képezi le ezt a függvényt, amikor egy ODBC 3*.x* alkalmazás ODBC 2*.x* illesztővel dolgozik, tekintse meg Az alkalmazások visszamenőleges kompatibilitását biztosító helyettesítő függvények leképezésecímű témakört.

Szintaxis

  
SQLRETURN SQLFreeHandle(  
     SQLSMALLINT   HandleType,  
     SQLHANDLE     Handle);

Érvek

HandleType
[Bemenet] Az SQLFreeHandleáltal felszabadítandó fogópont típusa. Az alábbi értékek egyikének kell lennie:

SQL_HANDLE_DBC
SQL_HANDLE_DBC_INFO_TOKEN
SQL_HANDLE_DESC
SQL_HANDLE_ENV
SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN leírót csak az illesztőprogram-kezelő és az illesztőprogram használja. Az alkalmazások nem használhatják ezt a leírótípust. A SQL_HANDLE_DBC_INFO_TOKEN további információkért lásd: Connection-Pool Tudatosság fejlesztése ODBC-illesztőben.

Ha HandleType nem tartozik ezek közé az értékek közé, SQLFreeHandle SQL_INVALID_HANDLE ad vissza.

kezelése
[Bemenet] A felszabadítandó fogópont.

Visszatér

SQL_SUCCESS, SQL_ERROR vagy SQL_INVALID_HANDLE.

Ha SQLFreeHandle SQL_ERROR ad vissza, a leíró továbbra is érvényes.

Diagnosztika

Ha SQLFreeHandle SQL_ERROR ad vissza, egy társított SQLSTATE-érték szerezhető be azon leíró diagnosztikai adatstruktúrájából, amelyet SQLFreeHandle megpróbált felszabadítani, de nem sikerült. Az alábbi táblázat felsorolja a SQLFreeHandle által visszaadott SQLSTATE-értékeket, és ismerteti azokat a függvény kontextusában; a(z) "(DM)" jelölés megelőzi a Driver Manager által visszaadott SQLSTATES-ek leírását. Az egyes SQLSTATE-értékekhez társított visszatérési kód SQL_ERROR, kivéve, ha másként van feltüntetve.

SQLSTATE	Hiba	Leírás
HY000	Általános hiba	Hiba történt, amely miatt nem volt konkrét SQLSTATE, és amelyhez nem definiáltak implementációspecifikus SQLSTATE-t. Az SQLGetDiagRec által a *MessageText pufferben visszaadott hibaüzenet leírja a hibát és annak okát.
HY001	Memóriafoglalási hiba	Az illesztőprogram nem tudta lefoglalni a függvény végrehajtásának vagy befejezésének támogatásához szükséges memóriát.
HY010	Függvényütemezési hiba	(DM) A HandleType argumentum SQL_HANDLE_ENV volt, és legalább egy kapcsolat lefoglalt vagy csatlakoztatott állapotban volt. SQLDisconnect és sqlFreeHandle SQL_HANDLE_DBC HandleType kell meghívni minden kapcsolathoz, mielőtt SQLFreeHandleHandleType SQL_HANDLE_ENV-val hívna meg. (DM) A HandleType argumentum SQL_HANDLE_DBC volt, és a függvény meghívása a SQLDisconnect meghívása előtt történt. (DM) A HandleType argumentum SQL_HANDLE_DBC volt. A függvény aszinkron módon történő végrehajtásának meghívása Handle használatával történt, és a függvény a függvény meghívásakor továbbra is végrehajtásra került. (DM) A HandleType argumentum SQL_HANDLE_STMT volt. SQLExecute, SQLExecDirect, SQLBulkOperationsvagy SQLSetPos meghívása az utasításkezelővel történt, és SQL_NEED_DATA adott vissza. Ezt a függvényt az összes adatvégrehajtási paraméter vagy oszlop adatküldése előtt hívták meg. (DM) A HandleType argumentum SQL_HANDLE_STMT volt. Egy aszinkron módon végrehajtó függvényt hívtak meg az utasításkezelőn vagy a társított kapcsolati leírón, és a függvény a függvény meghívásakor továbbra is végrehajtásra került. (DM) A HandleType argumentum SQL_HANDLE_DESC volt. A társított kapcsolati leírón aszinkron módon végrehajtó függvényt hívtak meg; és a függvény még mindig a függvény meghívásakor lett végrehajtva. (DM) Az SQLFreeHandle meghívása előtt nem adták ki az összes leányvállalati leírót és egyéb erőforrást. (DM) SQLExecute, SQLExecDirectvagy SQLMoreResults a Handle és HandleType SQL_HANDLE_STMT vagy SQL_HANDLE_DESC visszaadott SQL_PARAM_DATA_AVAILABLE egyik utasításleírójához lett meghívva. Ez a függvény az összes streamelt paraméter adatainak lekérése előtt lett meghívva.
HY013	Memóriakezelési hiba	A HandleType argumentum SQL_HANDLE_STMT vagy SQL_HANDLE_DESC volt, és a függvényhívás nem dolgozható fel, mert az alapul szolgáló memóriaobjektumok nem érhetők el, valószínűleg a memóriahiány miatt.
HY017	Érvénytelen az automatikusan lefoglalt leíró leíró leírójának használata.	(DM) A Leíró argumentum egy automatikusan lefoglalt leíró leírójának leírója lett beállítva.
HY117	A kapcsolat ismeretlen tranzakciós állapot miatt fel van függesztve. Csak a leválasztási és írásvédett függvények engedélyezettek.	(DM) További információ a felfüggesztett állapotról: SQLEndTran függvény.
HYT01	A kapcsolat időtúllépése lejárt	A kapcsolat időtúllépési időtartama lejárt, mielőtt az adatforrás válaszolt a kérésre. A kapcsolat időtúllépési időszaka SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Az illesztőprogram nem támogatja ezt a függvényt	(DM) A HandleType argumentum SQL_HANDLE_DESC volt, az illesztőprogram pedig ODBC 2.x illesztőprogram volt. (DM) A HandleType argumentum SQL_HANDLE_STMT volt, és az illesztőprogram nem volt érvényes ODBC-illesztő.

Megjegyzések

SQLFreeHandle a következő szakaszokban ismertetett környezetek, kapcsolatok, utasítások és leírók leíróinak felszabadítására szolgál. A leírókkal kapcsolatos általános információkért lásd: Fogópontok.

Az alkalmazások nem használhatnak fogópontot a felszabadítás után; az Illesztőprogram-kezelő nem ellenőrzi a leíró érvényességét egy függvényhívásban.

Környezeti leíró felszabadítása

Mielőtt meghívja SQLFreeHandle SQL_HANDLE_ENV HandleType, az alkalmazásnak meg kell hívnia SQLFreeHandle egy HandleType SQL_HANDLE_DBC a környezetben lefoglalt összes kapcsolathoz. Ellenkező esetben az SQLFreeHandle hívása SQL_ERROR és a környezetet adja vissza, és az aktív kapcsolat érvényes marad. További információ: Környezeti leírók és A Környezeti leírókiosztása.

Ha a környezet megosztott környezet, a SQLFreeHandle SQL_HANDLE_ENV HandleType meghívó alkalmazás már nem fér hozzá a környezethez a hívás után, de a környezet erőforrásai nem feltétlenül szabadulnak fel. Az SQLFreeHandle hívása mérsékeli a környezet referenciaszámát. A referenciaszámot az illesztőprogram-kezelő tartja karban. Ha nem éri el a nullát, a megosztott környezet nem lesz felszabadítva, mert egy másik összetevő továbbra is használja. Ha a hivatkozási szám eléri a nullát, a megosztott környezet erőforrásai felszabadulnak.

Kapcsolati leíró felszabadítása

Mielőtt meghívja SQLFreeHandle HandleType SQL_HANDLE_DBC, az alkalmazásnak meg kell hívnia SQLDisconnect a kapcsolathoz, ha ezen a leírón van kapcsolat*.* Ellenkező esetben az SQLFreeHandle hívása SQL_ERROR ad vissza, és a kapcsolat érvényes marad.

További információ: Kapcsolatkezelők és Az adatforrás vagy az illesztőprogramleválasztása.

Utasításkezelő felszabadítása

Az SQLFreeHandle HandleType hívása felszabadítja a SQL_HANDLE_STMT SQLAllocHandle SQL_HANDLE_STMT HandleType hívása által lefoglalt összes erőforrást. Amikor egy alkalmazás meghívja SQLFreeHandle egy függőben lévő eredményt tartalmazó utasítás felszabadítására, a függőben lévő eredmények törlődnek. Amikor egy alkalmazás felszabadít egy utasításfogópontot, az illesztőprogram felszabadítja a leíróhoz társított négy automatikusan lefoglalt leírót. További információ: Utasításkezelők és Utasításkezelőfelszabadítása.

Figyelje meg, hogy SQLDisconnect automatikusan elveti a kapcsolaton megnyitott utasításokat és leírókat.

Leírófogópont felszabadítása

Az SQLFreeHandle HandleType SQL_HANDLE_DESC hívása felszabadítja a leíró leíró leíróját a Leíró. Az SQLFreeHandle hívása nem szabadít fel az alkalmazás által lefoglalt memóriát, amely az SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR és SQL_DESC_OCTET_LENGTH_PTR) mutatómezővel hivatkozhat az Handleleíró rekordjára. Az illesztőprogram által a nem mutató mezőkhöz lefoglalt memória felszabadul a fogópont felszabadításakor. A felhasználó által lefoglalt leírófogópontok felszabadításakor minden olyan utasítás, amely szerint a felszabadított leíró vissza lett rendelve a megfelelő automatikusan kiosztott leíróleíró fogópontokhoz.

Jegyzet

Az ODBC 2*.x* illesztőprogramok nem támogatják a leíró fogópontok felszabadítását, ahogyan a leíró fogópontok kiosztását sem.

Figyelje meg, hogy SQLDisconnect automatikusan elveti a kapcsolaton megnyitott utasításokat és leírókat. Amikor egy alkalmazás felszabadít egy utasításfogópontot, az illesztőprogram felszabadítja a leíróhoz társított összes automatikusan létrehozott leírót.

További információ a leírókról: Leírók.

Példa kódra

További kódmintákért lásd SQLBrowseConnect és SQLConnect.

Kód

// SQLFreeHandle.cpp  
// compile with: user32.lib odbc32.lib  
#include <windows.h>  
#include <sqlext.h>  
#include <stdio.h>  
  
int main() {  
   SQLRETURN retCode;  
   HWND desktopHandle = GetDesktopWindow();   // desktop's window handle  
   SQLCHAR connStrbuffer[1024];  
   SQLSMALLINT connStrBufferLen;  
  
   // Initialize the environment, connection, statement handles.  
   SQLHENV henv = NULL;   // Environment     
   SQLHDBC hdbc = NULL;   // Connection handle  
   SQLHSTMT hstmt = NULL;   // Statement handle  
  
   // Allocate the environment.  
   retCode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
  
   // Set environment attributes.  
   retCode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, -1);  
  
   // Allocate the connection.  
   retCode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
  
   // Set the login timeout.  
   retCode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)10, 0);  
  
   // Let the user select the data source and connect to the database.  
   retCode = SQLDriverConnect(hdbc, desktopHandle, (SQLCHAR *)"Driver={SQL Server}", SQL_NTS, connStrbuffer, 1025, &connStrBufferLen, SQL_DRIVER_PROMPT);  
  
   retCode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
   // Free handles, and disconnect.     
   if (hstmt) {   
      SQLFreeHandle(SQL_HANDLE_STMT, hstmt);  
      hstmt = NULL;   
   }  
   if (hdbc) {   
      SQLDisconnect(hdbc);  
      SQLFreeHandle(SQL_HANDLE_DBC, hdbc);  
      hdbc = NULL;   
   }  
   if (henv) {   
      SQLFreeHandle(SQL_HANDLE_ENV, henv);  
      henv = NULL;   
   }  
}

További információ:	Lát
Fogópont kiosztása	SQLAllocHandle függvény
Utasításfeldolgozás megszakítása	SQLCancel-függvény
Kurzornév beállítása	SQLSetCursorName függvény

Lásd még:

ODBC API-referencia
ODBC-fejlécfájlok
ODBC-mintaprogram

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2025-01-02