Функция 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 см. в разработке Connection-Pool осведомленности вдрайвера 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 используется для освобождения дескрипторов для сред, подключений, инструкций и дескрипторов, как описано в следующих разделах. Общие сведения об дескрипторах см. в разделе Handles.

Приложение не должно использовать дескриптор после освобождения; Диспетчер драйверов не проверяет допустимость дескриптора в вызове функции.

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

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

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