Функция SQLFreeHandle

Статья
08/21/2023

Соответствия
Представлена версия: соответствие стандартам 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

Поделиться через

Функция SQLFreeHandle

Синтаксис

Аргументы

Возвраты

Диагностика

Комментарии

Освобождение дескриптора среды

Освобождение дескриптора подключения

Освобождение дескриптора инструкции

Освобождение дескриптора

Пример кода

Код

См. также

Обратная связь

Дополнительные ресурсы

Поделиться через

Функция SQLFreeHandle

Синтаксис

Аргументы

Возвраты

Диагностика

Комментарии

Освобождение дескриптора среды

Освобождение дескриптора подключения

Освобождение дескриптора инструкции

Освобождение дескриптора

Пример кода

Код

Связанные функции

См. также

Обратная связь

Дополнительные ресурсы