Функция SQLFreeHandle
Соответствия
Представлена версия: соответствие стандартам ODBC 3.0: ISO 92
Сводка
SQLFreeHandle освобождает ресурсы, связанные с определенной средой, подключением, оператором или дескриптором.
Заметка
Эта функция является универсальной функцией для освобождения дескрипторов. Он заменяет функции ODBC 2.0 SQLFreeConnect (для освобождения дескриптора подключения) и SQLFreeEnv (для освобождения дескриптора среды). SQLFreeConnect и SQLFreeEnv не рекомендуется использовать в ODBC 3*.x*. SQLFreeHandle также заменяет функцию ODBC 2.0 SQLFreeStmt (с параметром SQL_DROP) для освобождения дескриптора инструкции. Дополнительные сведения см. в разделе "Комментарии". Дополнительные сведения о том, что диспетчер драйверов сопоставляет эту функцию с тем, когда приложение ODBC 3*.x* работает с драйвером ODBC 2*.x*, см. в разделе "Функции сопоставления замены для обратной совместимости приложений".
Синтаксис
SQLRETURN SQLFreeHandle(
SQLSMALLINT HandleType,
SQLHANDLE Handle);
Аргументы
HandleType
[Входные данные] Тип дескриптора, освобождаемого SQLFreeHandle. Необходимо установить одно из следующих значений.
SQL_HANDLE_DBC
SQL_HANDLE_DBC_INFO_TOKEN
SQL_HANDLE_DESC
SQL_HANDLE_ENV
SQL_HANDLE_STMT
SQL_HANDLE_DBC_INFO_TOKEN дескриптор используется только диспетчером драйверов и драйвером. Приложения не должны использовать этот тип дескриптора. Дополнительные сведения о SQL_HANDLE_DBC_INFO_TOKEN см. в статье "Разработка осведомленности о пуле подключений" в драйвере ODBC.
Если HandleType не является одним из этих значений, SQLFreeHandle возвращает SQL_INVALID_HANDLE.
Дескриптор
[Входные данные] Дескриптор для освобождения.
Возвраты
SQL_SUCCESS, SQL_ERROR или SQL_INVALID_HANDLE.
Если SQLFreeHandle возвращает SQL_ERROR, дескриптор по-прежнему действителен.
Диагностика
Когда SQLFreeHandle возвращает SQL_ERROR, связанное значение SQLSTATE может быть получено из структуры диагностических данных для дескриптора, который SQLFreeHandle пытался освободить, но не удалось. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLFreeHandle и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемых диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.
| SQLSTATE | Error | Description |
|---|---|---|
| HY000 | Общая ошибка | Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину. |
| HY001 | Ошибка выделения памяти | Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции. |
| HY010 | Ошибка последовательности функций | (DM) Аргумент HandleType был SQL_HANDLE_ENV, и по крайней мере одно соединение находилось в выделенном или подключенном состоянии. SQLDisconnect и SQLFreeHandle с помощью HandleType SQL_HANDLE_DBC необходимо вызвать для каждого подключения перед вызовом SQLFreeHandle с помощью HandleType SQL_HANDLE_ENV. (DM) Аргумент HandleType был SQL_HANDLE_DBC, и функция была вызвана перед вызовом SQLDisconnect для подключения. (DM) Аргумент HandleType был SQL_HANDLE_DBC. Асинхронно выполняющаяся функция была вызвана дескриптором, и функция по-прежнему выполнялась при вызове этой функции. (DM) Аргумент HandleType был SQL_HANDLE_STMT. SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos были вызваны дескриптором инструкции и возвращены SQL_NEED_DATA. Эта функция была вызвана до отправки данных для всех параметров выполнения или столбцов. (DM) Аргумент HandleType был SQL_HANDLE_STMT. Асинхронно выполняющаяся функция была вызвана дескриптором инструкции или связанной дескриптором соединения, и функция по-прежнему выполнялась при вызове этой функции. (DM) Аргумент HandleType был SQL_HANDLE_DESC. Асинхронно выполняющаяся функция была вызвана на связанном дескрипторе подключения; и функция по-прежнему выполняется при вызове этой функции. (DM) Все дочерние дескрипторы и другие ресурсы не были выпущены до вызова SQLFreeHandle . (DM) SQLExecute, SQLExecDirect или SQLMoreResults был вызван для одного из дескрипторов инструкций, связанных с Handle и HandleType, было установлено значение SQL_HANDLE_STMT или SQL_HANDLE_DESC возвращены SQL_PARAM_DATA_AVAILABLE. Эта функция была вызвана до получения данных для всех потоковых параметров. |
| HY013 | Ошибка управления памятью | Аргумент HandleType был SQL_HANDLE_STMT или SQL_HANDLE_DESC, и вызов функции не удалось обработать, так как базовые объекты памяти не могут быть доступны, возможно, из-за низкой памяти. |
| HY017 | Недопустимое использование дескриптора автоматического выделенного дескриптора. | (DM) Аргумент дескриптора был задан для дескриптора автоматически выделенного дескриптора. |
| HY117 | Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. | (DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function. |
| HYT01 | Время ожидания для подключения истекло | Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Драйвер не поддерживает эту функцию | (DM) Аргумент HandleType был SQL_HANDLE_DESC, и драйвер был драйвером ODBC 2*.x*. (DM) Аргумент HandleType был SQL_HANDLE_STMT, и драйвер не был допустимым драйвером ODBC. |
Комментарии
SQLFreeHandle используется для освобождения дескрипторов сред, подключений, инструкций и дескрипторов, как описано в следующих разделах. Общие сведения об дескрипторах см. в разделе "Дескрипторы".
Приложение не должно использовать дескриптор после освобождения; Диспетчер драйверов не проверяет допустимость дескриптора в вызове функции.
Освобождение дескриптора среды
Прежде чем вызывать SQLFreeHandle с помощью HandleType SQL_HANDLE_ENV, приложение должно вызывать SQLFreeHandle с помощью HandleType SQL_HANDLE_DBC для всех подключений, выделенных в среде. В противном случае вызов SQLFreeHandle возвращает SQL_ERROR и среду, а любое активное подключение остается допустимым. Дополнительные сведения см. в разделе "Дескриптор среды" и "Выделение дескриптора среды".
Если среда является общей средой, приложение, которое вызывает SQLFreeHandle с HandleType SQL_HANDLE_ENV больше не имеет доступа к среде после вызова, но ресурсы среды не обязательно освобождаются. Вызов SQLFreeHandle уменьшает количество ссылок среды. Счетчик ссылок поддерживается диспетчером драйверов. Если она не достигает нуля, общая среда не освобождается, так как она по-прежнему используется другим компонентом. Если число ссылок достигает нуля, ресурсы общей среды освобождаются.
Освобождение дескриптора подключения
Прежде чем вызывать SQLFreeHandle с помощью HandleType SQL_HANDLE_DBC, приложение должно вызвать SQLDisconnect для подключения, если на этом дескрипторе есть подключение.* В противном случае вызов SQLFreeHandle возвращает SQL_ERROR, а соединение остается допустимым.
Дополнительные сведения см. в разделе "Дескрипторы подключений" и "Отключение от источника данных" или "Драйвер".
Освобождение дескриптора инструкции
Вызов SQLFreeHandle с помощью HandleType SQL_HANDLE_STMT освобождает все ресурсы, выделенные вызовом SQLAllocHandle с помощью HandleType SQL_HANDLE_STMT. Когда приложение вызывает SQLFreeHandle для освобождения инструкции, которая имеет ожидающие результаты, удаляются ожидающие результаты. Когда приложение освобождает дескриптор инструкции, драйвер освобождает четыре автоматически выделенных дескриптора, связанных с этим дескриптором. Дополнительные сведения см. в разделе "Дескриптор инструкций " и "Освобождение дескриптора инструкций".
Обратите внимание, что SQLDisconnect автоматически удаляет все инструкции и дескрипторы, открытые в соединении.
Освобождение дескриптора
Вызов SQLFreeHandle с помощью HandleType SQL_HANDLE_DESC освобождает дескриптор дескриптора в Handle. Вызов SQLFreeHandle не освобождает никакой памяти, выделенной приложением, которое может ссылаться на поле указателя (включая SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR и SQL_DESC_OCTET_LENGTH_PTR) любой записи дескриптора дескриптора. Память, выделенная драйвером для полей, которые не являются полями указателя, освобождается при освобождении дескриптора. Когда дескриптор, выделенный пользователем, освобождается, все операторы, которые освобожденный дескриптор был связан с возвратом к соответствующим дескрипторам автоматически выделенных дескрипторов.
Заметка
Драйверы ODBC 2*.x* не поддерживают дескриптор освобождения дескрипторов, так же, как они не поддерживают выделение дескрипторов дескрипторов.
Обратите внимание, что SQLDisconnect автоматически удаляет все инструкции и дескрипторы, открытые в соединении. Когда приложение освобождает дескриптор инструкции, драйвер освобождает все автоматически созданные дескрипторы, связанные с этим дескриптором.
Дополнительные сведения о дескрипторах см. в разделе "Дескрипторы".
Пример кода
Дополнительные примеры кода см. в разделе SQLBrowseConnect и SQLConnect.
Код
// 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;
}
}
Связанные функции
| Сведения | Раздел |
|---|---|
| Выделение дескриптора | Функция SQLAllocHandle |
| Отмена обработки инструкций | Функция SQLCance |
| Задание имени курсора | Функция SQLSetCursorName |
См. также
Справочник по API ODBC
Файлы заголовков ODBC
Образец программы ODBC
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по