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 드라이버Connection-Pool 인식 개발을 참조하세요.

HandleType 이러한 값 중 하나가 아닌 경우 SQLFreeHandle SQL_INVALID_HANDLE 반환합니다.

핸들
[입력] 해제할 핸들입니다.

반환

SQL_SUCCESS, SQL_ERROR 또는 SQL_INVALID_HANDLE.

SQLFreeHandle SQL_ERROR 반환하는 경우 핸들은 여전히 유효합니다.

진단

SQLFreeHandle SQL_ERROR 반환하는 경우 SQLFreeHandle을 핸들에 대한 진단 데이터 구조에서 연결된 SQLSTATE 값을 가져올 수 있습니다. 다음 표에서는 SQLFreeHandle 일반적으로 반환되는 SQLSTATE 값을 나열하고 이 함수의 컨텍스트에서 각각에 대해 설명합니다. "(DM)" 표기법은 드라이버 관리자가 반환한 SQLSTATE에 대한 설명 앞에 섰습니다. 달리 명시되지 않는 한 각 SQLSTATE 값과 연결된 반환 코드는 SQL_ERROR.

코멘트

SQLFreeHandle 다음 섹션에 설명된 대로 환경, 연결, 문 및 설명자에 대한 핸들을 해제하는 데 사용됩니다. 핸들에 대한 일반적인 내용은 핸들참조하세요.

애플리케이션이 해제된 후에는 핸들을 사용하면 안 됩니다. 드라이버 관리자는 함수 호출에서 핸들의 유효성을 확인하지 않습니다.

환경 핸들 해제

HandleType SQL_HANDLE_ENV 사용하여 SQLFreeHandle 호출하기 전에 애플리케이션은 환경에서 할당된 모든 연결에 대해 HandleType SQL_HANDLE_DBC SQLFreeHandle 호출해야 합니다. 그렇지 않으면 SQLFreeHandle 호출은 SQL_ERROR 반환하고 환경 및 활성 연결은 유효한 상태로 유지됩니다. 자세한 내용은 환경 핸들 및 환경 핸들할당을 참조하세요.

환경이 공유 환경인 경우 HandleType SQL_HANDLE_ENV SQLFreeHandle을 호출하는 애플리케이션은 호출 후 더 이상 환경에 액세스할 수 없지만 환경의 리소스가 반드시 해제되지는 않습니다. SQLFreeHandle 호출하면 환경의 참조 수가 감소합니다. 참조 수는 드라이버 관리자에 의해 유지 관리됩니다. 0에 도달하지 않으면 공유 환경이 다른 구성 요소에서 계속 사용되므로 해제되지 않습니다. 참조 수가 0에 도달하면 공유 환경의 리소스가 해제됩니다.

연결 핸들 해제

SQL_HANDLE_DBC HandleType 사용하여 SQLFreeHandle 호출하기 전에 애플리케이션은 이 핸들에 연결이 있는 경우 연결에 SQLDisconnect 호출해야 합니다.* 그렇지 않으면 SQLFreeHandle 호출하면 SQL_ERROR 반환되고 연결이 유효합니다.

자세한 내용은 연결 핸들 및 데이터 원본 또는 드라이버연결 끊기를 참조하세요.

문 핸들 해제

SQL_HANDLE_STMT HandleType 사용하여 SQLFreeHandle 호출하면 SQL_HANDLE_STMT HandleType 사용하여 SQLAllocHandle 호출하여 할당된 모든 리소스를 해제합니다. 애플리케이션이 SQLFreeHandle 호출하여 보류 중인 결과가 있는 문을 해제하면 보류 중인 결과가 삭제됩니다. 애플리케이션에서 문 핸들을 해제하면 드라이버는 해당 핸들과 연결된 자동으로 할당된 설명자 4개를 해제합니다. 자세한 내용은 문 핸들 및 문 핸들해제를 참조하세요.

SQLDisconnect 자동으로 연결에서 열린 문과 설명자를 삭제합니다.

설명자 핸들 해제

SQL_HANDLE_DESC HandleType 사용하여 SQLFreeHandle 호출하면 Handle설명자 핸들이 해제됩니다. SQLFreeHandle 호출은 Handle설명자 레코드의 포인터 필드(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;   
   }  
}  

관련 함수

참고 항목

ODBC API 참조
ODBC 헤더 파일
샘플 ODBC 프로그램