FUNKCE SQLFreeHandle
shoda
Zavedená verze: Dodržování standardů ODBC 3.0: ISO 92
souhrnu
SQLFreeHandle uvolní prostředky přidružené ke konkrétnímu prostředí, připojení, příkazu nebo popisovači popisovače.
Poznámka
Tato funkce je obecná funkce pro uvolnění popisovačů. Nahrazuje funkce ODBC 2.0 SQLFreeConnect (pro uvolnění popisovače připojení) a SQLFreeEnv (pro uvolnění úchytu prostředí). SQLFreeConnect a SQLFreeEnv jsou v rozhraní ODBC 3*.x* zastaralé. SQLFreeHandle nahrazuje také funkci ODBC 2.0 sqlFreeStmt (s SQL_DROP Option) pro uvolnění popisovače příkazu. Další informace najdete v tématu Komentáře. Další informace o tom, na co Správce ovladačů mapuje tuto funkci, když aplikace ODBC 3*.x* pracuje s ovladačem ODBC 2*.x*, naleznete v tématu Mapování náhradních funkcí pro zpětnou kompatibilitu aplikací.
Syntax
SQLRETURN SQLFreeHandle(
SQLSMALLINT HandleType,
SQLHANDLE Handle);
Argumenty
HandleType
[Vstup] Typ úchytu, který má být uvolněn SQLFreeHandle. Musí to být jedna z následujících hodnot:
SQL_HANDLE_DBC
SQL_HANDLE_DBC_INFO_TOKEN
SQL_HANDLE_DESC
SQL_HANDLE_ENV
SQL_HANDLE_STMT
SQL_HANDLE_DBC_INFO_TOKEN popisovač používá pouze Správce ovladačů a ovladač. Aplikace by neměly používat tento typ popisovače. Další informace o SQL_HANDLE_DBC_INFO_TOKEN naleznete v tématu Vývoj Connection-Pool povědomí o ovladači ODBC.
Pokud HandleType není jedna z těchto hodnot, SQLFreeHandle vrátí SQL_INVALID_HANDLE.
popisovač
[Vstup] Rukojeť, která se má uvolnit.
Návraty
SQL_SUCCESS, SQL_ERROR nebo SQL_INVALID_HANDLE.
Pokud SQLFreeHandle vrátí SQL_ERROR, popisovač je stále platný.
Diagnostika
Když SQLFreeHandle vrátí SQL_ERROR, může být přidružená hodnota SQLSTATE získána ze struktury diagnostických dat pro popisovač, který SQLFreeHandle pokus o uvolnění, ale nemohl. Následující tabulka uvádí hodnoty SQLSTATE, které obvykle vrací SQLFreeHandle a vysvětluje každý z nich v kontextu této funkce; notace "(DM)" předchází popisy funkcí SQLSTATEs vrácených správcem ovladačů. Návratový kód přidružený ke každé hodnotě SQLSTATE je SQL_ERROR, pokud není uvedeno jinak.
| SQLSTATE | Chyba | Popis |
|---|---|---|
| HY000 | Obecná chyba | Došlo k chybě, pro kterou nebyla definována žádná specifická funkce SQLSTATE a pro kterou nebyla definována žádná implementace sqlSTATE. Chybová zpráva vrácená sqlGetDiagRec v *MessageText vyrovnávací paměti popisuje chybu a její příčinu. |
| HY001 | Chyba přidělení paměti | Ovladač nemohl přidělit paměť, která je nutná k podpoře provádění nebo dokončování funkce. |
| HY010 | Chyba posloupnosti funkcí | (DM) Argument HandleType byl SQL_HANDLE_ENV a alespoň jedno připojení bylo v přiděleném nebo připojeném stavu.
sqlDisconnect a sqlFreeHandle s HandleType SQL_HANDLE_DBC musí být volána pro každé připojení před voláním SQLFreeHandle s HandleType SQL_HANDLE_ENV. (DM) Argument HandleType byl SQL_HANDLE_DBC a funkce byla volána před voláním SQLDisconnect připojení. (DM) Argument HandleType byl SQL_HANDLE_DBC. Asynchronně spouštěná funkce byla volána s Popisovač a funkce se pořád spouštěla, když byla tato funkce volána. (DM) Argument HandleType byl SQL_HANDLE_STMT. SQLExecute, SQLExecDirect, SQLBulkOperationsnebo SQLSetPos byl volána pomocí popisovače příkazu a vrácena SQL_NEED_DATA. Tato funkce byla volána před odesláním dat pro všechny parametry provádění dat nebo sloupce. (DM) Argument HandleType byl SQL_HANDLE_STMT. Asynchronní provádění funkce bylo volána v popisovači příkazu nebo v přidruženém popisovači připojení a funkce se stále spouštěla, když byla tato funkce volána. (DM) Argument HandleType byl SQL_HANDLE_DESC. Na přidruženém popisovači připojení byla volána asynchronně spuštěná funkce; a funkce se stále spouštěla, když byla tato funkce volána. (DM) Před voláním SQLFreeHandle nebyly vydány všechny podřízené popisovače a další prostředky. (DM) sqlExecute, SQLExecDirectnebo sqlMoreResults byl volána pro jeden z popisovačů příkazů přidružených k Popisovač a HandleType byl nastaven na SQL_HANDLE_STMT nebo SQL_HANDLE_DESC vrácených SQL_PARAM_DATA_AVAILABLE. Tato funkce byla volána před načtením dat pro všechny streamované parametry. |
| HY013 | Chyba správy paměti | Argument HandleType byl SQL_HANDLE_STMT nebo SQL_HANDLE_DESC a volání funkce nebylo možné zpracovat, protože základní paměťové objekty nelze získat přístup, pravděpodobně kvůli nedostatku paměti. |
| HY017 | Neplatné použití popisovače automaticky přiděleného popisovače | (DM) Argument Popisovač byl nastaven na popisovač pro automaticky přidělený popisovač. |
| HY117 | Připojení je pozastaveno kvůli neznámému stavu transakce. Jsou povoleny pouze funkce pro odpojení a jen pro čtení. | (DM) Další informace o pozastaveném stavu naleznete v tématu FUNKCE SQLEndTran. |
| HYT01 | Vypršel časový limit připojení | Platnost časového limitu připojení vypršela, než zdroj dat odpověděl na žádost. Doba časového limitu připojení je nastavena prostřednictvím SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Ovladač tuto funkci nepodporuje. | (DM) Argument HandleType byl SQL_HANDLE_DESC a ovladač byl ovladač ODBC 2*.x*. (DM) Argument HandleType byl SQL_HANDLE_STMT a ovladač nebyl platným ovladačem ODBC. |
Komentáře
SQLFreeHandle se používá k bezplatnému zpracování pro prostředí, připojení, příkazy a popisovače, jak je popsáno v následujících částech. Obecné informace o popisovačích naleznete v tématu Popisovače.
Aplikace by neměla používat popisovač po uvolnění; Správce ovladačů nekontroluje platnost popisovače ve volání funkce.
Uvolnění úchytu prostředí
Před voláním SQLFreeHandle s HandleType SQL_HANDLE_ENV musí aplikace volat SQLFreeHandle s HandleType SQL_HANDLE_DBC pro všechna připojení přidělená v prostředí. V opačném případě volání SQLFreeHandle vrátí SQL_ERROR a prostředí a jakékoli aktivní připojení zůstane platné. Další informace najdete v tématu Obslužné rutiny prostředí a přidělenípopisovače prostředí .
Pokud je prostředí sdílené prostředí, aplikace, která volá SQLFreeHandle s HandleType SQL_HANDLE_ENV už nemá přístup k prostředí po volání, ale prostředky prostředí nejsou nutně uvolněny. Volání SQLFreeHandle sníží počet odkazů prostředí. Počet odkazů udržuje správce ovladačů. Pokud nedosáhne nuly, sdílené prostředí není uvolněno, protože ho stále používá jiná komponenta. Pokud počet odkazů dosáhne nuly, uvolní se prostředky sdíleného prostředí.
Uvolnění popisovače připojení
Před voláním SQLFreeHandle s HandleType SQL_HANDLE_DBC musí aplikace volat SQLDisconnect pro připojení, pokud je připojení k tomuto popisovači*.* Jinak volání SQLFreeHandle vrátí SQL_ERROR a připojení zůstane platné.
Další informace naleznete v tématu Obslužné rutiny připojení a odpojení od zdroje dat nebo ovladače.
Uvolnění popisovače příkazu
Volání SQLFreeHandle s HandleType SQL_HANDLE_STMT uvolní všechny prostředky přidělené voláním SQLAllocHandle s HandleType SQL_HANDLE_STMT. Když aplikace volá SQLFreeHandle uvolnit příkaz, který obsahuje čekající výsledky, čekající výsledky budou odstraněny. Když aplikace uvolní popisovač příkazu, ovladač uvolní čtyři automaticky přidělené popisovače přidružené k danému popisovači. Další informace naleznete v tématu příkaz handles a uvolnění popisovač příkazu.
Všimněte si, že SQLDisconnect automaticky zahodí všechny příkazy a popisovače otevřené v připojení.
Uvolnění popisovače popisovače
Volání SQLFreeHandle s HandleType SQL_HANDLE_DESC uvolní popisovač v Popisovač. Volání SQLFreeHandle neuvolní žádnou paměť přidělenou aplikací, na kterou může odkazovat pole ukazatele (včetně SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR a SQL_DESC_OCTET_LENGTH_PTR) jakéhokoli záznamu popisovače Handle. Paměť přidělená ovladačem pro pole, která nejsou pole ukazatelem, se uvolní při uvolnění popisovače. Když je popisovač popisovače přidělený uživatelem uvolněný, všechny příkazy, které byl uvolněný popisovač přidružený k vrácení příslušných automaticky přidělených popisovačů.
Poznámka
Ovladače ODBC 2*.x* nepodporují uvolnění popisovačů, stejně jako nepodporují přidělování popisovačů popisovače.
Všimněte si, že SQLDisconnect automaticky zahodí všechny příkazy a popisovače otevřené v připojení. Když aplikace uvolní popisovač příkazu, ovladač uvolní všechny automaticky generované popisovače přidružené k danému popisovači.
Další informace o popisovači naleznete v tématu popisovače.
Příklad kódu
Další ukázky kódu najdete v tématu SQLBrowseConnect a 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;
}
}
Související funkce
| Informace o | Vidět |
|---|---|
| Přidělení úchytu | funkce SQLAllocHandle |
| Zrušení zpracování příkazů | funkce SQLCancel |
| Nastavení názvu kurzoru | funkce SQLSetCursorName |
Viz také
Referenční
soubory hlaviček ODBC