다음을 통해 공유


SQLFreeStmt 함수

규칙
버전 소개: 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 HandleTypeHandle 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 헤더 파일