SQLCancel 함수
규칙
버전 소개: ODBC 1.0 표준 준수: ISO 92
요약
SQLCancel 은 문에 대한 처리를 취소합니다.
연결 또는 문에 대한 처리를 취소하려면 SQLCancelHandle 함수를 사용합니다.
구문
SQLRETURN SQLCancel(
SQLHSTMT StatementHandle);
인수
StatementHandle
[입력] 문 핸들입니다.
반품
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR 또는 SQL_INVALID_HANDLE.
진단
SQLCancel이 SQL_ERROR 또는 SQL_SUCCESS_WITH_INFO 반환하는 경우 SQL_HANDLE_STMT HandleType 및 Handle of StatementHandle을 사용하여 SQLGetDiagRec를 호출하여 관련 SQLSTATE 값을 가져올 수 있습니다. 다음 표에서는 SQLCancel에서 일반적으로 반환되는 SQLSTATE 값을 나열하고 이 함수의 컨텍스트에서 각 값을 설명합니다. "(DM)" 표기법은 드라이버 관리자가 반환한 SQLSTATE에 대한 설명 앞에 나와 있습니다. 달리 명시되지 않는 한 각 SQLSTATE 값과 연결된 반환 코드는 SQL_ERROR.
| SQLSTATE | 오류 | 설명 |
|---|---|---|
| 01000 | 일반 경고 | 드라이버 관련 정보 메시지입니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| HY000 | 일반 오류 | 특정 SQLSTATE가 없고 구현별 SQLSTATE가 정의되지 않은 오류가 발생했습니다. *MessageText 버퍼 인수에서 SQLGetDiagRec에서 반환된 오류 메시지는 오류와 그 원인을 설명합니다. |
| HY001 | 메모리 할당 오류 | 드라이버가 함수 실행 또는 완료를 지원하는 데 필요한 메모리를 할당할 수 없습니다. |
| HY010 | 함수 시퀀스 오류 | (DM) StatementHandle과 연결된 연결 핸들에 대해 비동기적으로 실행되는 함수가 호출되었습니다. 이 비동기 함수는 SQLCancel 함수가 호출되었을 때 계속 실행되었습니다. (DM) StatementHandle과 연결된 연결 핸들에서 비동기 작업이 진행 중이므로 취소 작업이 실패했습니다. |
| HY013 | 메모리 관리 오류 | 메모리 조건이 낮기 때문에 기본 메모리 개체에 액세스할 수 없기 때문에 함수 호출을 처리할 수 없습니다. |
| HY018 | 서버에서 취소 요청을 거부했습니다. | 서버에서 취소 요청을 거부했습니다. |
| HY117 | 알 수 없는 트랜잭션 상태로 인해 연결이 일시 중단됩니다. 연결 끊기 및 읽기 전용 함수만 허용됩니다. | (DM) 일시 중단 상태에 대한 자세한 내용은 SQLEndTran 함수를 참조 하세요. |
| HYT01 | 연결 제한 시간이 만료됨 | 데이터 원본이 요청에 응답하기 전에 연결 제한 시간이 만료되었습니다. 연결 제한 시간은 SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr를 통해 설정됩니다. |
| IM001 | 드라이버는 이 함수를 지원하지 않습니다. | (DM) StatementHandle과 연결된 드라이버는 함수를 지원하지 않습니다. |
설명
SQLCancel은 문에서 다음 유형의 처리를 취소할 수 있습니다.
문에서 비동기적으로 실행되는 함수입니다.
데이터가 필요한 문의 함수입니다.
다른 스레드의 문에서 실행되는 함수입니다.
ODBC 2에서x. 문에서 처리가 수행되지 않을 때 애플리케이션이 SQLCancel을 호출하는 경우 SQLCancel은 SQL_CLOSE 옵션을 사용하여 SQLFreeStmt와 동일한 효과를 줍니다. 이 동작은 완전성을 위해서만 정의되며 애플리케이션은 SQLFreeStmt 또는 SQLCloseCursor를 호출하여 커서를 닫아야 합니다.
문 또는 데이터가 필요한 문의 함수에서 비동기적으로 실행되는 함수를 취소하기 위해 SQLCancel을 호출하면 취소되는 함수에 의해 게시된 진단 레코드가 지워지고 SQLCancel이 자체 진단 레코드를 게시합니다. SQLCancel을 호출하여 다른 스레드의 문에서 실행되는 함수를 취소할 때는 취소되는 함수의 진단 레코드를 지우지 않고 자체 진단 레코드를 게시하지 않습니다.
비동기 처리 취소
애플리케이션이 함수를 비동기적으로 호출한 후 함수를 반복적으로 호출하여 처리가 완료되었는지 여부를 확인합니다. 함수가 여전히 처리 중이면 SQL_STILL_EXECUTING 반환합니다. 함수가 처리를 완료하면 다른 코드를 반환합니다.
SQL_STILL_EXECUTING 반환하는 함수를 호출한 후에 애플리케이션은 SQLCancel을 호출하여 함수를 취소할 수 있습니다. 취소 요청이 성공하면 드라이버는 SQL_SUCCESS 반환합니다. 이 메시지는 함수가 실제로 취소되었음을 나타내지 않습니다. 취소 요청이 처리되었음을 나타냅니다. 함수가 실제로 취소되는 경우 또는 취소되는 경우 드라이버 종속 및 데이터 원본에 종속됩니다. 반환 코드가 SQL_STILL_EXECUTING 않을 때까지 애플리케이션은 원래 함수를 계속 호출해야 합니다. 함수가 성공적으로 취소되면 반환 코드가 SQL_ERROR SQLSTATE HY008(작업이 취소됨)입니다. 함수가 정상적인 처리를 완료하면 함수가 성공하거나 SQL_ERROR 경우 반환 코드가 SQL_SUCCESS 또는 SQL_SUCCESS_WITH_INFO 함수가 실패하면 HY008(작업 취소)이 아닌 SQLSTATE가 반환됩니다.
참고 항목
ODBC 3.5에서는 문에서 처리가 수행되지 않을 때 SQLCancel에 대한 호출이 SQL_CLOSE 옵션을 사용하여 SQLFreeStmt로 처리되지 않지만 전혀 효과가 없습니다. 커서를 닫기 위해 애플리케이션은 SQLCancel이 아닌 SQLCloseCursor를 호출해야 합니다.
비동기 처리에 대한 자세한 내용은 비동기 실행을 참조하세요.
데이터가 필요한 함수 취소
SQLExecute 또는 SQLExecDirect가 SQL_NEED_DATA 반환한 후 모든 실행 시 데이터 매개 변수에 대한 데이터를 전송하기 전에 애플리케이션은 SQLCancel을 호출하여 문 실행을 취소할 수 있습니다. 문이 취소된 후 애플리케이션은 SQLExecute 또는 SQLExecDirect를 다시 호출할 수 있습니다. 자세한 내용은 SQLBindParameter를 참조 하세요.
SQLBulkOperations 또는 SQLSetPos가 SQL_NEED_DATA 반환한 후 모든 실행 시 데이터 열에 대한 데이터를 전송하기 전에 애플리케이션에서 SQLCancel을 호출하여 작업을 취소할 수 있습니다. 작업이 취소된 후 애플리케이션은 SQLBulkOperations 또는 SQLSetPos를 다시 호출할 수 있습니다. 취소는 커서 상태 또는 현재 커서 위치에 영향을 주지 않습니다. 자세한 내용은 SQLBulkOperations 또는 SQLSetPos를 참조하세요.
다른 스레드에서 실행되는 함수 취소
다중 스레드 애플리케이션에서 애플리케이션은 다른 스레드에서 실행 중인 함수를 취소할 수 있습니다. 함수를 취소하기 위해 애플리케이션은 대상 함수에서 사용하는 것과 동일한 문 핸들을 사용하지만 다른 스레드에서 SQLCancel을 호출합니다. 함수가 취소되는 방법은 드라이버와 운영 체제에 따라 달라집니다. 비동기적으로 실행되는 함수를 취소할 때와 마찬가지로 SQLCancel의 반환 코드는 드라이버가 요청을 성공적으로 처리했는지 여부만 나타냅니다. SQL_SUCCESS 또는 SQL_ERROR만 반환할 수 있습니다. 진단 정보가 반환되지 않습니다. 원래 함수가 취소되면 SQL_ERROR 및 SQLSTATE HY008(작업이 취소됨)을 반환합니다.
문 실행을 취소하기 위해 다른 스레드에서 SQLCancel을 호출할 때 SQL 문을 실행하는 경우 취소가 성공하는 동안 실행이 성공하고 SQL_SUCCESS 반환할 수 있습니다. 이 경우 드라이버 관리자는 문 실행에 의해 열린 커서가 취소에 의해 닫혀 있다고 가정하므로 애플리케이션은 커서를 사용할 수 없습니다.
스레딩에 대한 자세한 내용은 다중 스레딩을 참조 하세요.
관련 함수
| 추가 정보 | 참조 |
|---|---|
| 매개 변수에 버퍼 바인딩 | SQLBindParameter 함수 |
| 대량 삽입 또는 업데이트 작업 수행 | SQLBulkOperations 함수 |
| SQLCancel의 기능 외에도 연결 핸들에서 비동기적으로 실행되는 함수를 취소합니다. | SQLCancelHandle 함수 |
| SQL 문 실행 | SQLExecDirect 함수 |
| 준비된 SQL 문 실행 | SQLExecute 함수 |
| 문 핸들 해제 | SQLFreeStmt |
| 진단 레코드의 필드 또는 진단 헤더의 필드 가져오기 | SQLGetDiagField 함수 |
| 진단 데이터 구조의 여러 필드 가져오기 | SQLGetDiagRec 함수 |
| 다음 매개 변수를 반환하여 에 대한 데이터를 보냅니다. | SQLParamData 함수 |
| 실행 시 매개 변수 데이터 보내기 | SQLPutData 함수 |
| 행 집합에 커서 배치, 행 집합의 데이터 새로 고침 또는 결과 집합의 데이터 업데이트 또는 삭제 | SQLSetPos 함수 |