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 반환합니다.

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

반품

SQL_SUCCESS, SQL_ERROR 또는 SQL_INVALID_HANDLE.

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

진단

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

SQLSTATE	Error	설명
HY000	일반 오류	특정 SQLSTATE가 없고 구현별 SQLSTATE가 정의되지 않은 오류가 발생했습니다. *MessageText 버퍼의 SQLGetDiagRec에서 반환된 오류 메시지는 오류와 그 원인을 설명합니다.
HY001	메모리 할당 오류	드라이버가 함수 실행 또는 완료를 지원하는 데 필요한 메모리를 할당할 수 없습니다.
HY010	함수 시퀀스 오류	(DM) HandleType 인수가 SQL_HANDLE_ENV 하나 이상의 연결이 할당되거나 연결된 상태였습니다. HandleType이 SQL_HANDLE_DBC SQLDisconnect 및 SQLFreeHandle 은 SQL_HANDLE_ENV HandleType을 사용하여 SQLFreeHandle을 호출하기 전에 각 연결에 대해 호출해야 합니다. (DM) HandleType 인수가 SQL_HANDLE_DBC 연결에 대해 SQLDisconnect를 호출하기 전에 함수가 호출되었습니다. (DM) HandleType 인수가 SQL_HANDLE_DBC. Handle을 사용하여 비동기적으로 실행되는 함수가 호출되었고 이 함수가 호출되었을 때 함수가 계속 실행되고 있었습니다. (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 함수를 참조 하세요.
HYT01	연결 제한 시간이 만료됨	데이터 원본이 요청에 응답하기 전에 연결 제한 시간이 만료되었습니다. 연결 제한 시간은 SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr를 통해 설정됩니다.
IM001	드라이버는 이 함수를 지원하지 않습니다.	(DM) HandleType 인수가 SQL_HANDLE_DESC 드라이버가 ODBC 2.x 드라이버였습니다. (DM) HandleType 인수가 SQL_HANDLE_STMT 드라이버가 유효한 ODBC 드라이버가 아닙니다.

주석

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

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

환경 핸들 해제

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

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

연결 핸들 해제

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

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

문 핸들 해제

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

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

설명자 핸들 해제

HandleType이 SQL_HANDLE_DESC SQLFreeHandle을 호출하면 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 함수

참고 항목

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

SQLFreeHandle 함수

구문

인수

반품

진단

주석

환경 핸들 해제

연결 핸들 해제

문 핸들 해제

설명자 핸들 해제

코드 예

코드

참고 항목

피드백

피드백

추가 리소스

SQLFreeHandle 함수

구문

인수

반품

진단

주석

환경 핸들 해제

연결 핸들 해제

문 핸들 해제

설명자 핸들 해제

코드 예

코드

관련 함수

참고 항목

피드백

피드백

추가 리소스