SQLCancelHandle 함수
규칙
도입된 버전: ODBC 3.8 표준 준수: 없음
대부분의 ODBC 3.8 이상 드라이버는 이 함수를 구현할 것으로 예상됩니다. 드라이버가 그렇지 않으면 Handle 매개 변수에서 연결 핸들을 사용하여 SQLCancelHandle을 호출하면 IM001의 SQLSTATE를 사용하여 SQL_ERROR 반환하고 'Driver는 이 함수를 지원하지 않습니다.' 핸들 매개 변수로 문 핸들이 있는 SQLCancelHandle에 대한 호출은 드라이버 관리자가 SQLCancel에 대한 호출에 매핑되고 드라이버가 SQLCancel을 구현하는 경우 처리할 수 있습니다. 애플리케이션은 SQLGetFunctions를 사용하여 드라이버가 SQLCancelHandle을 지원하는지 확인할 수 있습니다.
요약
SQLCancelHandle 은 연결 또는 문에 대한 처리를 취소합니다. 드라이버 관리자는 HandleType이 SQL_HANDLE_STMT 때 SQLCancelHandle에 대한 호출을 SQLCancel 호출에 매핑합니다.
구문
SQLRETURN SQLCancelHandle(
SQLSMALLINT HandleType,
SQLHANDLE Handle);
인수
HandleType
[입력] 카셀 처리할 핸들의 형식입니다. 유효한 값은 SQL_HANDLE_DBC 또는 SQL_HANDLE_STMT.
Handle
[입력] 처리를 취소할 핸들입니다.
Handle이 HandleType에 지정된 형식의 유효한 핸들이 아니면 SQLCancelHandle은 SQL_INVALID_HANDLE 반환합니다.
반품
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR 또는 SQL_INVALID_HANDLE.
진단
SQLCancelHandle이 SQL_ERROR 또는 SQL_SUCCESS_WITH_INFO 반환하는 경우 SQL_HANDLE_STMT HandleType 및 문 핸들 핸들 또는 SQL_HANDLE_DBC HandleType 및 연결 핸들 핸들을 사용하여 SQLGetDiagRec를 호출하여 관련 SQLSTATE 값을 가져올 수 있습니다.
다음 표에서는 SQLCancelHandle에서 일반적으로 반환되는 SQLSTATE 값을 나열하고 이 함수의 컨텍스트에서 각 값을 설명합니다. 표기법 "(DM)"은 드라이버 관리자가 반환한 SQLSTATE에 대한 설명 앞에 나와 있습니다. 달리 명시되지 않는 한 각 SQLSTATE 값과 연결된 반환 코드는 SQL_ERROR.
| SQLSTATE | Error | 설명 |
|---|---|---|
| 01000 | 일반 경고 | 드라이버 관련 정보 메시지입니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| HY000 | 일반 오류 | 특정 SQLSTATE가 없고 구현별 SQLSTATE가 정의되지 않은 오류가 발생했습니다. *MessageText 버퍼 인수에서 SQLGetDiagRec에서 반환된 오류 메시지는 오류와 그 원인을 설명합니다. |
| HY001 | 메모리 할당 오류 | 드라이버가 함수 실행 또는 완료를 지원하는 데 필요한 메모리를 할당할 수 없습니다. |
| HY010 | 함수 시퀀스 오류 | 핸들과 연결된 문 핸들 중 하나에 대해 비동기적으로 실행되는 문 관련 함수가 호출되었고 HandleType이 SQL_HANDLE_DBC 설정되었습니다. SQLCancelHandle이 호출되었을 때 비동기 함수가 계속 실행 중입니다. (DM) HandleType 인수가 SQL_HANDLE_STMT 연결된 연결 핸들에서 비동기적으로 실행되는 함수가 호출되었으며 이 함수가 호출될 때 함수가 계속 실행되고 있었습니다. (DM) SQLExecute, SQLExecDirect 또는 SQLMoreResults는 Handle 및 HandleType과 연결된 문 핸들 중 하나가 SQL_HANDLE_DBC 설정되고 SQL_PARAM_DATA_AVAILABLE 반환되었습니다. 이 함수는 모든 스트리밍된 매개 변수에 대해 데이터를 검색하기 전에 호출되었습니다. CONNECTIONHandle에 대해 SQLBrowseConnect가 호출되었고 SQL_NEED_DATA 반환되었습니다. 이 함수는 검색 프로세스가 완료되기 전에 호출되었습니다. |
| HY013 | 메모리 관리 오류 | 메모리 조건이 낮기 때문에 기본 메모리 개체에 액세스할 수 없기 때문에 함수 호출을 처리할 수 없습니다. |
| HY092 | 잘못된 특성/옵션 식별자 | HandleType 이 SQL_HANDLE_ENV 또는 SQL_HANDLE_DESC 설정되었습니다. |
| HY117 | 알 수 없는 트랜잭션 상태로 인해 연결이 일시 중단됩니다. 연결 끊기 및 읽기 전용 함수만 허용됩니다. | (DM) 일시 중단 상태에 대한 자세한 내용은 SQLEndTran 함수를 참조 하세요. |
| HYT01 | 연결 제한 시간이 만료됨 | 데이터 원본이 요청에 응답하기 전에 연결 제한 시간이 만료되었습니다. 연결 제한 시간은 SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr를 통해 설정됩니다. |
| IM001 | 드라이버는 이 함수를 지원하지 않습니다. | (DM) Handle과 연결된 드라이버는 함수를 지원하지 않습니다. |
HandleType을 SQL_HANDLE_STMT 설정하여 SQLCancelHandle을 호출하는 경우 함수 SQLCancel에서 반환할 수 있는 모든 SQLSTATE를 반환할 수 있습니다.
주석
이 함수는 SQLCancel과 비슷하지만 연결 또는 문 핸들을 문 핸들이 아닌 매개 변수로 사용할 수 있습니다. 드라이버 관리자는 HandleType이 SQL_HANDLE_STMT 때 SQLCancelHandle에 대한 호출을 SQLCancel 호출에 매핑합니다. 이렇게 하면 드라이버가 SQLCancelHandle을 구현하지 않더라도 애플리케이션에서 SQLCancelHandle을 사용하여 문 작업을 취소할 수 있습니다.
문 작업을 취소하는 방법에 대한 자세한 내용은 SQLCancel 함수를 참조하세요.
핸들에서 진행 중인 작업이 없는 경우 SQLCancelHandle에 대한 호출은 영향을 주지 않습니다.
연결 핸들의 SQLCancelHandle 은 다음 유형의 처리를 취소할 수 있습니다.
연결에서 비동기적으로 실행되는 함수입니다.
다른 스레드의 연결 핸들에서 실행되는 함수입니다.
연결에서 비동기적으로 실행되는 함수를 취소하기 위해 SQLCancelHandle을 호출하면 SQLCancelHandle에서 게시한 진단 레코드가 취소되는 작업에서 반환된 레코드에 추가됩니다.그러나 SQLCancelHandle은 다른 스레드의 연결에서 실행되는 함수를 취소할 때 진단 레코드를 반환하지 않습니다.
SQLCancelHandle을 사용하여 SQLEndTran을 취소하면 연결이 일시 중단된 상태로 전환될 수 있습니다. 일시 중단 상태에 대한 자세한 내용은 SQLEndTran 함수를 참조 하세요.
참고 항목
Windows 7보다 오래된 Windows 운영 체제에 배포될 애플리케이션에서 SQLCancelHandle을 사용하는 방법에 대한 자세한 내용은 호환성 매트릭스를 참조하세요.
연결 관련 비동기 처리 취소
함수가 SQL_STILL_EXECUTING 반환하는 경우 애플리케이션은 SQLCancelHandle을 호출하여 작업을 취소할 수 있습니다. 취소 요청이 성공 하면 SQLCancelHandle 은 SQL_SUCCESS 반환합니다. 원래 함수가 취소되었음을 의미하지는 않습니다. 취소 요청이 처리되었음을 나타냅니다. 드라이버와 데이터 원본은 작업이 취소되는 시기 또는 시기를 결정합니다. 반환 코드가 SQL_STILL_EXECUTING 않을 때까지 애플리케이션은 원래 함수를 계속 호출해야 합니다. 원래 함수가 취소된 경우 반환 코드는 SQL_ERROR SQLSTATE HY008(작업이 취소됨)입니다. 원래 함수가 정상적인 처리를 완료한 경우(취소되지 않음) 반환 코드는 SQL_SUCCESS 또는 SQL_SUCCESS_WITH_INFO, 원래 함수가 실패한 경우 HY008(작업 취소)이 아닌 SQLSTATE와 SQL_ERROR.
다른 스레드에서 실행되는 함수 취소
다중 스레드 애플리케이션에서 애플리케이션은 다른 스레드에서 실행 중인 작업을 취소할 수 있습니다. 작업을 취소하기 위해 애플리케이션은 함수에서 사용하는 핸들이 아닌 다른 스레드에서 SQLCancelHandle을 호출합니다. 드라이버와 운영 체제는 작업을 취소하는 방법을 결정합니다. SQLCancelHandle 반환 코드는 드라이버가 요청을 처리하여 SQL_SUCCESS 또는 SQL_ERROR 반환하는지 여부를 나타냅니다(진단 정보가 반환되지 않음). 원래 함수의 처리가 취소되면 원래 함수는 SQL_ERROR 및 SQLSTATE HY008(작업이 취소됨)을 반환합니다.
함수를 취소하기 위해 다른 스레드에서 SQLCancelHandle을 호출할 때 함수를 실행하는 경우 함수가 성공하고 취소가 적용되기 전에 SQL_SUCCESS 반환할 수 있습니다. SQLCancelHandle이 작업을 취소하기 전에 작업이 완료된 경우에는 SQLCancelHandle에 대한 호출이 적용되지 않습니다.
관련 함수
| 추가 정보 | 참조 |
|---|---|
| 문 핸들에서 비동기적으로 실행되는 함수를 취소하거나, 데이터가 필요한 문에서 함수를 취소하거나, 다른 스레드의 문에서 실행되는 함수를 취소합니다. | SQLCancel 함수 |