Функция SQLFreeHandle

Соответствия
Представлена версия: соответствие стандартам ODBC 3.0: ISO 92

Сводка
SQLFreeHandle освобождает ресурсы, связанные с определенной средой, подключением, оператором или дескриптором.

Синтаксис

  
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, если не указано иное.

Комментарии

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) любой записи дескриптора дескриптора. Память, выделенная драйвером для полей, которые не являются полями указателя, освобождается при освобождении дескриптора. Когда дескриптор, выделенный пользователем, освобождается, все операторы, которые освобожденный дескриптор был связан с возвратом к соответствующим дескрипторам автоматически выделенных дескрипторов.

Обратите внимание, что 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;   
   }  
}  

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

См. также

Справочник по API ODBC
Файлы заголовков ODBC
Образец программы ODBC