SQLFreeHandle, functie
conformance
Versie geïntroduceerd: NALEVING van ODBC 3.0-standaarden: ISO 92
Samenvattings-
SQLFreeHandle resources vrij die zijn gekoppeld aan een specifieke omgeving, verbinding, instructie of descriptor-ingang.
Notitie
Deze functie is een algemene functie voor het vrijmaken van ingangen. Het vervangt de ODBC 2.0-functies SQLFreeConnect- (voor het vrijmaken van een verbindingsgreep) en SQLFreeEnv- (voor het vrijmaken van een omgevingshandgreep). SQLFreeConnect en SQLFreeEnv- zijn beide afgeschaft in ODBC 3*.x*. SQLFreeHandle- vervangt ook de functie ODBC 2.0 SQLFreeStmt (door de SQL_DROP Option) om een instructiegreep vrij te maken. Zie 'Opmerkingen' voor meer informatie. Zie voor meer informatie over wat Driver Manager deze functie toe wijst wanneer een ODBC 3*.x*-toepassing werkt met een ODBC 2*.x*-stuurprogramma, Vervangingsfuncties toewijzen voor achterwaartse compatibiliteit van toepassingen.
Syntaxis
SQLRETURN SQLFreeHandle(
SQLSMALLINT HandleType,
SQLHANDLE Handle);
Argumenten
HandleType-
[Invoer] Het type ingang dat moet worden vrijgemaakt door SQLFreeHandle-. Moet een van de volgende waarden zijn:
SQL_HANDLE_DBC
SQL_HANDLE_DBC_INFO_TOKEN
SQL_HANDLE_DESC
SQL_HANDLE_ENV
SQL_HANDLE_STMT
SQL_HANDLE_DBC_INFO_TOKEN ingang wordt alleen gebruikt door Driver Manager en stuurprogramma. Toepassingen mogen dit handletype niet gebruiken. Zie Ontwikkelen Connection-Pool Awareness in een ODBC-stuurprogrammavoor meer informatie over SQL_HANDLE_DBC_INFO_TOKEN.
Als HandleType- geen van deze waarden is, retourneert SQLFreeHandle- SQL_INVALID_HANDLE.
verwerken
[Invoer] De handgreep die moet worden vrijgemaakt.
Retourneert
SQL_SUCCESS, SQL_ERROR of SQL_INVALID_HANDLE.
Als SQLFreeHandle- SQL_ERROR retourneert, is de ingang nog steeds geldig.
Diagnostiek
Wanneer SQLFreeHandle- SQL_ERROR retourneert, kan er een bijbehorende SQLSTATE-waarde worden verkregen uit de structuur van diagnostische gegevens voor de ingang die SQLFreeHandle probeert vrij te maken, maar niet. De volgende tabel bevat de SQLSTATE-waarden die doorgaans worden geretourneerd door SQLFreeHandle- en legt elke waarden uit in de context van deze functie; de notatie (DM)' voorafgaat aan de beschrijvingen van SQLSTATEs die worden geretourneerd door Driver Manager. De retourcode die is gekoppeld aan elke SQLSTATE-waarde is SQL_ERROR, tenzij anders vermeld.
| SQLSTATE | Fout | Beschrijving |
|---|---|---|
| HY000 | Algemene fout | Er is een fout opgetreden waarvoor er geen specifieke SQLSTATE is en waarvoor geen implementatiespecifieke SQLSTATE is gedefinieerd. Het foutbericht dat is geretourneerd door SQLGetDiagRec- in de *MessageText buffer beschrijft de fout en de oorzaak ervan. |
| HY001 | Fout bij geheugentoewijzing | Het stuurprogramma kan geen geheugen toewijzen dat vereist is om de uitvoering of voltooiing van de functie te ondersteunen. |
| HY010 | Fout in functiereeks | (DM) Het argument HandleType is SQL_HANDLE_ENV en ten minste één verbinding heeft een toegewezen of verbonden status.
SQLDisconnect en SQLFreeHandle- met een HandleType- van SQL_HANDLE_DBC moet worden aangeroepen voor elke verbinding voordat u SQLFreeHandle- aanroept met een HandleType- van SQL_HANDLE_ENV. (DM) Het argument HandleType is SQL_HANDLE_DBC en de functie is aangeroepen voordat SQLDisconnect- voor de verbinding werd aangeroepen. (DM) Het argument HandleType is SQL_HANDLE_DBC. Er is een asynchroon uitgevoerde functie aangeroepen met Handle en de functie werd nog steeds uitgevoerd toen deze functie werd aangeroepen. (DM) Het argument HandleType is SQL_HANDLE_STMT. SQLExecute, SQLExecDirect, SQLBulkOperationsof SQLSetPos is aangeroepen met de instructiegreep en SQL_NEED_DATA geretourneerd. Deze functie is aangeroepen voordat gegevens werden verzonden voor alle parameters of kolommen voor uitvoering van gegevens. (DM) Het argument HandleType is SQL_HANDLE_STMT. Er is een asynchroon uitgevoerde functie aangeroepen op de instructiegreep of in de bijbehorende verbindingsgreep en de functie werd nog steeds uitgevoerd toen deze functie werd aangeroepen. (DM) Het argument HandleType is SQL_HANDLE_DESC. Er is een asynchroon uitgevoerde functie aangeroepen op de bijbehorende verbindingsgreep; en de functie werd nog steeds uitgevoerd toen deze functie werd aangeroepen. (DM) Alle ondersteunende ingangen en andere resources zijn niet vrijgegeven voordat SQLFreeHandle- werd aangeroepen. (DM) SQLExecute, SQLExecDirectof SQLMoreResults is aangeroepen voor een van de instructiegrepen die zijn gekoppeld aan de Handle en HandleType is ingesteld op SQL_HANDLE_STMT of SQL_HANDLE_DESC geretourneerd SQL_PARAM_DATA_AVAILABLE. Deze functie is aangeroepen voordat gegevens zijn opgehaald voor alle gestreamde parameters. |
| HY013 | Fout bij geheugenbeheer | Het argument HandleType is SQL_HANDLE_STMT of SQL_HANDLE_DESC en de functie-aanroep kan niet worden verwerkt omdat de onderliggende geheugenobjecten niet kunnen worden geopend, mogelijk vanwege onvoldoende geheugen. |
| HY017 | Ongeldig gebruik van een automatisch toegewezen descriptorgreep. | (DM) Het argument Handle is ingesteld op de ingang voor een automatisch toegewezen descriptor. |
| HY117 | De verbinding is onderbroken vanwege een onbekende transactiestatus. Alleen de verbinding verbreken en alleen-lezenfuncties zijn toegestaan. | (DM) Zie SQLEndTran Functionvoor meer informatie over de onderbroken status. |
| HYT01 | Time-out voor verbinding verlopen | De time-outperiode voor de verbinding is verlopen voordat de gegevensbron op de aanvraag heeft gereageerd. De time-outperiode voor de verbinding wordt ingesteld via SQLSetConnectAttr-, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Stuurprogramma biedt geen ondersteuning voor deze functie | (DM) Het argument HandleType is SQL_HANDLE_DESC en het stuurprogramma was een ODBC 2*.x*-stuurprogramma. (DM) Het argument HandleType is SQL_HANDLE_STMT en het stuurprogramma was geen geldig ODBC-stuurprogramma. |
Opmerkingen
SQLFreeHandle- wordt gebruikt voor vrije ingangen voor omgevingen, verbindingen, instructies en descriptors, zoals beschreven in de volgende secties. Zie Handlesvoor algemene informatie over ingangen.
Een toepassing mag geen ingang gebruiken nadat deze is vrijgemaakt; Driver Manager controleert niet de geldigheid van een ingang in een functie-aanroep.
Een omgevingsgreep vrijmaken
Voordat SQLFreeHandle- wordt aangeroepen met een HandleType- van SQL_HANDLE_ENV, moet een toepassing SQLFreeHandle- aanroepen met een HandleType- van SQL_HANDLE_DBC voor alle verbindingen die zijn toegewezen in de omgeving. Anders retourneert de aanroep naar SQLFreeHandle- SQL_ERROR en de omgeving en elke actieve verbinding geldig blijft. Zie Environment Handles and Allocating the Environment Handlevoor meer informatie.
Als de omgeving een gedeelde omgeving is, heeft de toepassing die SQLFreeHandle- aanroept met een HandleType- van SQL_HANDLE_ENV geen toegang meer tot de omgeving na de aanroep, maar de resources van de omgeving zijn niet noodzakelijkerwijs vrijgemaakt. De aanroep van SQLFreeHandle de referentieaantallen van de omgeving verlagen. Het referentieaantal wordt onderhouden door Driver Manager. Als deze niet nul bereikt, wordt de gedeelde omgeving niet vrijgemaakt, omdat deze nog steeds wordt gebruikt door een ander onderdeel. Als het aantal verwijzingen nul bereikt, worden de resources van de gedeelde omgeving vrijgemaakt.
Een verbindingsgreep vrijmaken
Voordat SQLFreeHandle- wordt aangeroepen met een HandleType- van SQL_HANDLE_DBC, moet een toepassing SQLDisconnect- aanroepen voor de verbinding als er een verbinding is op deze ingang*.* Anders retourneert de aanroep naar SQLFreeHandle SQL_ERROR en blijft de verbinding geldig.
Zie Verbindingsgrepen en Verbinding verbreken met een gegevensbron of stuurprogrammavoor meer informatie.
Een instructiegreep vrijmaken
Een aanroep van SQLFreeHandle- met een HandleType- van SQL_HANDLE_STMT maakt alle resources die zijn toegewezen door een aanroep naar SQLAllocHandle- met een HandleType- van SQL_HANDLE_STMT. Wanneer een toepassing SQLFreeHandle- aanroept om een instructie met in behandeling zijnde resultaten vrij te maken, worden de resultaten verwijderd die in behandeling zijn. Wanneer een toepassing een instructiegreep vrij maakt, maakt het stuurprogramma de vier automatisch toegewezen descriptors vrij die aan die ingang zijn gekoppeld. Zie Instructiehandgrepen en Een instructiegreepvrijmaken voor meer informatie.
U ziet dat SQLDisconnect automatisch alle instructies verwijdert en descriptors geopend zijn op de verbinding.
Een descriptorgreep vrijmaken
Een aanroep van SQLFreeHandle- met een HandleType- van SQL_HANDLE_DESC de descriptorgreep vrij in Handle. De aanroep van SQLFreeHandle- geeft geen geheugen vrij die is toegewezen door de toepassing waarnaar kan worden verwezen door een aanwijzerveld (inclusief SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR en SQL_DESC_OCTET_LENGTH_PTR) van een beschrijvingsrecord van Handle. Het geheugen dat door het stuurprogramma is toegewezen voor velden die geen aanwijzervelden zijn, wordt vrijgemaakt wanneer de ingang wordt vrijgemaakt. Wanneer een door de gebruiker toegewezen descriptorgreep wordt vrijgemaakt, zijn alle instructies die aan de vrije ingang zijn gekoppeld, teruggezet naar de respectieve automatisch toegewezen descriptor-ingangen.
Notitie
ODBC 2*.x*-stuurprogramma's bieden geen ondersteuning voor het vrijmaken van descriptor-ingangen, net zoals ze geen ondersteuning bieden voor het toewijzen van de descriptor-handles.
U ziet dat SQLDisconnect automatisch alle instructies verwijdert en descriptors geopend zijn op de verbinding. Wanneer een toepassing een instructiegreep vrijgeeft, worden alle automatisch gegenereerde descriptors die aan die ingang zijn gekoppeld, door het stuurprogramma vrijgemaakt.
Zie Descriptorsvoor meer informatie over descriptors.
Codevoorbeeld
Zie SQLBrowseConnect en SQLConnectvoor aanvullende codevoorbeelden.
Code
// 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;
}
}
Verwante functies
| Voor informatie over | Zien |
|---|---|
| Een ingang toewijzen | SQLAllocHandle-functie |
| Verwerking van instructie annuleren | SQLCancel Function- |
| Een cursornaam instellen | SQLSetCursorName-functie |
Zie ook
ODBC-API-verwijzing
ODBC-headerbestanden
odbc-voorbeeldprogramma