SQLFreeHandle-funktion
Efterlevnad
Version introducerad: ODBC 3.0 Standardefterlevnad: ISO 92
Sammanfattning
SQLFreeHandle frigör resurser som är associerade med en specifik miljö, anslutning, instruktion eller deskriptorreferens.
Not
Den här funktionen är en allmän funktion för att frigöra handtag. Den ersätter ODBC 2.0-funktionerna SQLFreeConnect- (för att frigöra ett anslutningshandtag) och SQLFreeEnv- (för att frigöra ett miljöhandtag). SQLFreeConnect och SQLFreeEnv är båda inaktuella i ODBC 3*.x*. SQLFreeHandle ersätter även funktionen ODBC 2.0 SQLFreeStmt (med SQL_DROP Option) för att frigöra en instruktionsreferens. Mer information finns i "Kommentarer". Mer information om vad Driver Manager mappar den här funktionen till när ett ODBC 3*.x*-program fungerar med en ODBC 2*.x*-drivrutin finns i Mapping Replacement Functions for Backward Compatibility of Applications.
Syntax
SQLRETURN SQLFreeHandle(
SQLSMALLINT HandleType,
SQLHANDLE Handle);
Argument
HandleType
[Indata] Den typ av referens som ska frigöras av SQLFreeHandle. Måste vara något av följande värden:
SQL_HANDLE_DBC
SQL_HANDLE_DBC_INFO_TOKEN
SQL_HANDLE_DESC
SQL_HANDLE_ENV
SQL_HANDLE_STMT
SQL_HANDLE_DBC_INFO_TOKEN handtag används endast av Drivrutinshanteraren och drivrutinen. Program bör inte använda den här referenstypen. Mer information om SQL_HANDLE_DBC_INFO_TOKEN finns i Utveckla Connection-Pool Medvetenhet i en ODBC-drivrutin.
Om HandleType inte är ett av dessa värden returnerar SQLFreeHandle SQL_INVALID_HANDLE.
Hantera
[Indata] Handtaget som ska frigöras.
Returnerar
SQL_SUCCESS, SQL_ERROR eller SQL_INVALID_HANDLE.
Om SQLFreeHandle- returnerar SQL_ERROR är handtaget fortfarande giltigt.
Diagnostik
När SQLFreeHandle- returnerar SQL_ERROR kan ett associerat SQLSTATE-värde hämtas från diagnostikdatastrukturen för handtaget som SQLFreeHandle- försökte frigöra men inte kunde. I följande tabell visas de SQLSTATE-värden som vanligtvis returneras av SQLFreeHandle- och förklarar var och en i kontexten för den här funktionen. notationen "(DM)" föregår beskrivningarna av SQLSTATEs som returneras av Driver Manager. Returkoden som är associerad med varje SQLSTATE-värde är SQL_ERROR, om inget annat anges.
| SQLSTATE | Fel | Beskrivning |
|---|---|---|
| HY000 | Allmänt fel | Ett fel uppstod för vilket det inte fanns någon specifik SQLSTATE och för vilken ingen implementeringsspecifik SQLSTATE definierades. Felmeddelandet som returneras av SQLGetDiagRec i bufferten *MessageText beskriver felet och orsaken. |
| HY001 | Fel vid minnesallokering | Drivrutinen kunde inte allokera minne som krävs för att stödja körning eller slutförande av funktionen. |
| HY010 | Funktionssekvensfel | (DM) Argumentet HandleType var SQL_HANDLE_ENV och minst en anslutning var i ett allokerat eller anslutet tillstånd.
SQLDisconnect och SQLFreeHandle med en HandleType- av SQL_HANDLE_DBC måste anropas för varje anslutning innan du anropar SQLFreeHandle- med en HandleType- av SQL_HANDLE_ENV. (DM) Argumentet HandleType var SQL_HANDLE_DBC och funktionen anropades innan SQLDisconnect- anropades för anslutningen. (DM) Argumentet HandleType var SQL_HANDLE_DBC. En asynkront körd funktion anropades med Handle och funktionen kördes fortfarande när den här funktionen anropades. (DM) Argumentet HandleType var SQL_HANDLE_STMT. SQLExecute, SQLExecDirect, SQLBulkOperationseller SQLSetPos anropades med instruktionshandtaget och returnerades SQL_NEED_DATA. Den här funktionen anropades innan data skickades för alla data-at-execution-parametrar eller kolumner. (DM) Argumentet HandleType var SQL_HANDLE_STMT. En funktion som körs asynkront anropades på instruktionshandtaget eller på det associerade anslutningshandtaget och funktionen kördes fortfarande när den här funktionen anropades. (DM) Argumentet HandleType var SQL_HANDLE_DESC. En funktion som körs asynkront anropades på det associerade anslutningshandtaget. och funktionen kördes fortfarande när den här funktionen anropades. (DM) Alla dotterbolagsreferenser och andra resurser släpptes inte innan SQLFreeHandle- anropades. (DM) SQLExecute, SQLExecDirecteller SQLMoreResults anropades för någon av de instruktionsreferenser som är associerade med Handle och HandleType har angetts till SQL_HANDLE_STMT eller SQL_HANDLE_DESC returnerades SQL_PARAM_DATA_AVAILABLE. Den här funktionen anropades innan data hämtades för alla strömmade parametrar. |
| HY013 | Minneshanteringsfel | Argumentet HandleType var SQL_HANDLE_STMT eller SQL_HANDLE_DESC och funktionsanropet kunde inte bearbetas eftersom de underliggande minnesobjekten inte kunde nås, eventuellt på grund av minnesbrist. |
| HY017 | Ogiltig användning av en automatiskt allokerad deskriptorreferens. | (DM) Argumentet Handle har angetts till referensen för en automatiskt allokerad beskrivning. |
| HY117 | Anslutningen pausas på grund av okänt transaktionstillstånd. Endast frånkopplings- och skrivskyddade funktioner tillåts. | (DM) Mer information om inaktiverat tillstånd finns i SQLEndTran Function. |
| HYT01 | Tidsgränsen för anslutningen har upphört att gälla | Tidsgränsen för anslutningen löpte ut innan datakällan svarade på begäran. Tidsgränsen för anslutningen anges via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Drivrutinen stöder inte den här funktionen | (DM) Argumentet HandleType var SQL_HANDLE_DESC och drivrutinen var en ODBC 2*.x*-drivrutin. (DM) Argumentet HandleType var SQL_HANDLE_STMT och drivrutinen var inte en giltig ODBC-drivrutin. |
Kommentarer
SQLFreeHandle- används för kostnadsfria referenser för miljöer, anslutningar, instruktioner och beskrivningar, enligt beskrivningen i följande avsnitt. Allmän information om referenser finns i Handles.
Ett program bör inte använda ett handtag när det har frigjorts. Driver Manager kontrollerar inte giltigheten för en referens i ett funktionsanrop.
Frigör ett miljöhandtag
Innan det anropar SQLFreeHandle- med en HandleType- av SQL_HANDLE_ENV måste ett program anropa SQLFreeHandle- med en HandleType- av SQL_HANDLE_DBC för alla anslutningar som allokeras i miljön. Annars returnerar anropet till SQLFreeHandle SQL_ERROR och miljön och alla aktiva anslutningar förblir giltiga. Mer information finns i Environment Handles and Allocating the Environment Handle.
Om miljön är en delad miljö har programmet som anropar SQLFreeHandle med en HandleType- av SQL_HANDLE_ENV inte längre åtkomst till miljön efter anropet, men miljöns resurser frigörs inte nödvändigtvis. Anropet till SQLFreeHandle minskar referensantalet för miljön. Referensantalet underhålls av Drivrutinshanteraren. Om den inte når noll frigörs inte den delade miljön eftersom den fortfarande används av en annan komponent. Om referensantalet når noll frigörs resurserna i den delade miljön.
Frigör ett anslutningshandtag
Innan det anropar SQLFreeHandle- med en HandleType- av SQL_HANDLE_DBC måste ett program anropa SQLDisconnect- för anslutningen om det finns en anslutning i det här handtaget*.* Annars returnerar anropet till SQLFreeHandle SQL_ERROR och anslutningen förblir giltig.
Mer information finns i Anslutningsreferenser och frånkoppling från en datakälla eller drivrutin.
Frigör ett instruktionshandtag
Ett anrop till SQLFreeHandle- med en HandleType- av SQL_HANDLE_STMT frigör alla resurser som allokerats av ett anrop till SQLAllocHandle med en HandleType- av SQL_HANDLE_STMT. När ett program anropar SQLFreeHandle för att frigöra en instruktion som har väntande resultat tas de väntande resultaten bort. När ett program frigör en instruktionsreferens frigör drivrutinen de fyra automatiskt allokerade deskriptorer som är associerade med handtaget. Mer information finns i -instruktionen hanterar och Frigör en instruktionsreferens.
Observera att SQLDisconnect automatiskt släpper alla instruktioner och beskrivningar som öppnas på anslutningen.
Frigör ett deskriptorhandtag
Ett anrop till SQLFreeHandle- med en HandleType- av SQL_HANDLE_DESC frigör beskrivningshandtaget i Handle. Anropet till SQLFreeHandle frigör inte något minne som allokeras av programmet som kan refereras av ett pekarfält (inklusive SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR och SQL_DESC_OCTET_LENGTH_PTR) för någon beskrivande post i Handle. Det minne som allokeras av drivrutinen för fält som inte är pekarfält frigörs när handtaget frigörs. När en användarallokerad deskriptorreferens frigörs, har alla instruktioner som det frigjorda handtaget associerats med återställts till respektive automatiskt allokerade deskriptorhandtag.
Not
ODBC 2*.x*-drivrutiner stöder inte friskrivning av deskriptorhandtag, precis som de inte stöder allokering av deskriptorhandtag.
Observera att SQLDisconnect automatiskt släpper alla instruktioner och beskrivningar som öppnas på anslutningen. När ett program frigör en instruktionsreferens frigör drivrutinen alla automatiskt genererade deskriptorer som är associerade med handtaget.
Mer information om deskriptorer finns i Descriptors.
Kodexempel
Ytterligare kodexempel finns i SQLBrowseConnect och SQLConnect.
Kod
// 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;
}
}
Relaterade funktioner
| Mer information om | Se |
|---|---|
| Allokera ett handtag | SQLAllocHandle-funktion |
| Avbryta instruktionsbearbetning | SQLCancel-funktion |
| Ange ett markörnamn | SQLSetCursorName-funktion |