SQLFreeStmt 함수

아티클
08/21/2023

규칙
버전 소개: ODBC 1.0 표준 준수: ISO 92

요약
SQLFreeStmt 는 특정 문과 연결된 처리를 중지하거나, 문과 연결된 열려 있는 커서를 닫거나, 보류 중인 결과를 삭제하거나, 필요에 따라 문 핸들과 연결된 모든 리소스를 해제합니다.

구문

  
SQLRETURN SQLFreeStmt(  
     SQLHSTMT       StatementHandle,  
     SQLUSMALLINT   Option);

인수

StatementHandle
[입력] 문 핸들

옵션
[입력] 다음 옵션 중 하나입니다.

SQL_ CLOSE: StatementHandle과 연결된 커서를 닫고(정의된 경우) 보류 중인 모든 결과를 삭제합니다. 애플리케이션은 나중에 동일하거나 다른 매개 변수 값으로 SELECT 문을 다시 실행하여 이 커서를 다시 열 수 있습니다. 커서가 열려 있지 않으면 이 옵션은 애플리케이션에 영향을 주지 않습니다. SQLCloseCursor 를 호출하여 커서를 닫을 수도 있습니다. 자세한 내용은 커서 닫기를 참조 하세요.

SQL_DROP: 이 옵션은 더 이상 사용되지 않습니다. SQL_DROP 옵션이 있는 SQLFreeStmt에 대한 호출은 드라이버 관리자에서 SQLFreeHandle에 매핑됩니다.

SQL_UNBIND: ARD의 SQL_DESC_COUNT 필드를 0으로 설정하여 지정된 StatementHandle에 대해 SQLBindCol로 바인딩된 모든 열 버퍼를 해제합니다. 책갈피 열의 바인딩을 해제하지 않습니다. 이렇게 하려면 책갈피 열에 대한 ARD의 SQL_DESC_DATA_PTR 필드가 NULL로 설정됩니다. 이 작업이 둘 이상의 문에서 공유되는 명시적으로 할당된 설명자에서 수행되는 경우 이 작업은 설명자를 공유하는 모든 문의 바인딩에 영향을 줍니다. 자세한 내용은 결과 검색 개요(기본)를 참조하세요.

SQL_RESET_PARAMS: 지정된 StatementHandle에 대해 SQLBindParameter 에서 설정한 모든 매개 변수 버퍼를 해제하여 APD의 SQL_DESC_COUNT 필드를 0으로 설정합니다. 이 작업이 둘 이상의 문에서 공유되는 명시적으로 할당된 설명자에서 수행되는 경우 이 작업은 설명자를 공유하는 모든 문의 바인딩에 영향을 줍니다. 자세한 내용은 바인딩 매개 변수를 참조 하세요.

반품

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR 또는 SQL_INVALID_HANDLE.

진단

SQLFreeStmt가 SQL_ERROR 또는 SQL_SUCCESS_WITH_INFO 반환하는 경우 SQL_HANDLE_STMT HandleType 및Handle of StatementHandle을 사용하여 SQLGetDiagRec 를 호출하여 관련 SQLSTATE 값을 가져올 수 있습니다. 다음 표에서는 일반적으로 SQLFreeStmt에서 반환되는 SQLSTATE 값을 나열하고 이 함수의 컨텍스트에서 각각에 대해 설명합니다. 표기법 "(DM)"은 드라이버 관리자가 반환한 SQLSTATE에 대한 설명 앞에 나와 있습니다. 달리 명시되지 않는 한 각 SQLSTATE 값과 연결된 반환 코드는 SQL_ERROR.

SQLSTATE	Error	설명
01000	일반 경고	드라이버 관련 정보 메시지입니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다.
HY000	일반 오류	특정 SQLSTATE가 없고 구현별 SQLSTATE가 정의되지 않은 오류가 발생했습니다. *MessageText 버퍼의 SQLGetDiagRec에서 반환된 오류 메시지는 오류와 그 원인을 설명합니다.
HY001	메모리 할당 오류	드라이버가 함수 실행 또는 완료를 지원하는 데 필요한 메모리를 할당할 수 없습니다.
HY010	함수 시퀀스 오류	(DM) StatementHandle과 연결된 연결 핸들에 대해 비동기적으로 실행되는 함수가 호출되었습니다. 이 비동기 함수는 SQLFreeStmt가 호출되었을 때 계속 실행되었습니다. (DM) SQLExecute, SQLExecDirect 또는 SQLMoreResults가 StatementHandle에 대해 호출되고 SQL_PARAM_DATA_AVAILABLE 반환되었습니다. 이 함수는 모든 스트리밍된 매개 변수에 대한 데이터를 검색하기 전에 SQL_RESET_PARAMS 위해 Option을 설정하여 호출되었습니다. (DM) StatementHandle에 대해 비동기적으로 실행되는 함수가 호출되었고 이 함수가 호출되었을 때에도 여전히 실행 중입니다. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations 또는 SQLSetPos가 StatementHandle에 대해 호출되고 SQL_NEED_DATA 반환되었습니다. 이 함수는 모든 실행 시 데이터 매개 변수 또는 열에 대한 데이터를 보내기 전에 호출되었습니다.
HY013	메모리 관리 오류	메모리 조건이 낮기 때문에 기본 메모리 개체에 액세스할 수 없기 때문에 함수 호출을 처리할 수 없습니다.
HY092	옵션 유형이 범위를 벗어났습니다.	(DM) Option 인수에 지정된 값이 다음과 없음: SQL_CLOSE SQL_DROP SQL_UNBIND SQL_RESET_PARAMS
HYT01	연결 제한 시간이 만료됨	데이터 원본이 요청에 응답하기 전에 연결 제한 시간이 만료되었습니다. 연결 제한 시간은 SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr를 통해 설정됩니다.
IM001	드라이버는 이 함수를 지원하지 않습니다.	(DM) StatementHandle과 연결된 드라이버는 함수를 지원하지 않습니다.

주석

SQL_CLOSE 옵션을 사용하여 SQLFreeStmt를 호출하는 것은 SQLCloseCursor를 호출하는 것과 같습니다. 단, 문에 커서가 열려 있지 않은 경우 SQL_CLOSE 있는 SQLFreeStmt는 애플리케이션에 영향을 주지 않습니다. 열려 있는 커서가 없으면 SQLCloseCursor를 호출하면 SQLSTATE 24000(잘못된 커서 상태)이 반환됩니다.

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

예

핸들을 해제하는 것이 좋은 프로그래밍 방법입니다. 그러나 간단히 하기 위해 다음 샘플에는 할당된 핸들을 해제하는 코드가 포함되지 않습니다. 핸들을 해제하는 방법의 예는 SQLFreeHandle 함수를 참조하세요.

// SQLFreeStmt.cpp  
// compile with: user32.lib odbc32.lib  
#include <windows.h>  
#include <sqlext.h>  
  
int main() {  
   // declare and initialize the environment, connection, statement handles  
   SQLHENV henv = NULL;   // Environment     
   SQLHDBC hdbc = NULL;   // Connection handle  
   SQLHSTMT hstmt = NULL;   // Statement handle  
  
   SQLRETURN retCode;  
   HWND desktopHandle = GetDesktopWindow();   // desktop's window handle  
   SQLCHAR connStrbuffer[1024];  
   SQLSMALLINT connStrBufferLen;  
   retCode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
   retCode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, -1);  
   retCode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
   retCode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)10, 0);  
   retCode = SQLDriverConnect(hdbc, desktopHandle, (SQLCHAR *)"Driver={SQL Server}", SQL_NTS, connStrbuffer, 1024 + 1, &connStrBufferLen, SQL_DRIVER_PROMPT);  
   retCode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
   retCode = SQLFreeStmt(hstmt, SQL_CLOSE);  
   retCode = SQLFreeStmt(hstmt, SQL_UNBIND);  
   retCode = SQLFreeStmt(hstmt, SQL_RESET_PARAMS);  
}

추가 정보	참조
핸들 할당	SQLAllocHandle 함수
문 처리 취소	SQLCancel 함수
커서 닫기	SQLCloseCursor 함수
핸들 해제	SQLFreeHandle 함수
커서 이름 설정	SQLSetCursorName 함수

참고 항목

ODBC API 참조
ODBC 헤더 파일

SQLFreeStmt 함수

구문

인수

반품

진단

주석

예

참고 항목

피드백

피드백

추가 리소스

SQLFreeStmt 함수

구문

인수

반품

진단

주석

예

관련 함수

참고 항목

피드백

피드백

추가 리소스