SQLExtendedFetch 함수
규칙
버전 도입: ODBC 1.0 표준 준수: 사용되지 않음
요약
SQLExtendedFetch 는 결과 집합에서 지정된 데이터 행 집합을 가져오고 모든 바인딩된 열에 대한 데이터를 반환합니다. 행 집합은 절대 또는 상대 위치 또는 책갈피로 지정할 수 있습니다.
참고 항목
ODBC 3*.x*에서 SQLExtendedFetch는 SQLFetchScroll로 대체되었습니다. ODBC 3*.x* 애플리케이션은 SQLExtendedFetch를 호출하지 않아야 합니다. 대신 SQLFetchScroll을 호출해야 합니다. 드라이버 관리자는 ODBC 2*.x* 드라이버로 작업할 때 SQLFetchScroll을 SQLExtendedFetch에 매핑합니다. ODBC 3*.x* 드라이버는 호출하는 ODBC 2*.x* 애플리케이션에서 작업하려는 경우 SQLExtendedFetch를 지원해야 합니다. 자세한 내용은 부록 G: 이전 버전과의 호환성을 위한 드라이버 지침에서 "메모" 및 블록 커서, 스크롤 가능한 커서 및 이전 버전과의 호환성을 참조하세요.
구문
SQLRETURN SQLExtendedFetch(
SQLHSTMT StatementHandle,
SQLUSMALLINT FetchOrientation,
SQLLEN FetchOffset,
SQLULEN * RowCountPtr,
SQLUSMALLINT * RowStatusArray);
인수
StatementHandle
[입력] 문 핸들입니다.
FetchOrientation
[입력] 인출 유형입니다. SQLFetchScroll의 FetchOrientation과 동일합니다.
FetchOffset
[입력] 가져올 행의 수입니다. 한 가지 예외를 제외하고 SQLFetchScroll의 FetchOffset과 동일합니다. FetchOrientation이 SQL_FETCH_BOOKMARK 때 FetchOffset은 책갈피의 오프셋이 아니라 고정 길이 책갈피입니다. 즉, SQLExtendedFetch 는 SQL_ATTR_FETCH_BOOKMARK_PTR 문 특성이 아니라 이 인수에서 책갈피를 검색합니다. 가변 길이 책갈피를 지원하지 않으며 책갈피에서 오프셋(0 이외의)에서 행 집합을 가져오는 것을 지원하지 않습니다.
RowCountPtr
[출력] 실제로 가져온 행 수를 반환할 버퍼에 대한 포인터입니다. 이 버퍼는 SQL_ATTR_ROWS_FETCHED_PTR 문 특성에 지정된 버퍼와 동일한 방식으로 사용됩니다. 이 버퍼는 SQLExtendedFetch에서만 사용됩니다. SQLFetch 또는 SQLFetchScroll에서 사용되지 않습니다.
RowStatusArray
[출력] 각 행의 상태를 반환할 배열에 대한 포인터입니다. 이 배열은 SQL_ATTR_ROW_STATUS_PTR 문 특성에 지정된 배열과 동일한 방식으로 사용됩니다.
그러나 이 배열의 주소는 IRD의 SQL_DESC_STATUS_ARRAY_PTR 필드에 저장되지 않습니다. 또한 이 배열은 SQLExtendedFetch 이후에 호출되는 경우 SQLExtendedFetch 및 sqlBulkOperations에서만 SQL_ADD 또는 SQLSetPos 작업을 사용하여 사용됩니다. SQLFetch 또는 SQLFetchScroll에서 사용되지 않으며 SQLFetch 또는 SQLFetchScroll 이후에 호출되는 경우 SQLBulkOperations 또는 SQLSetPos에서 사용되지 않습니다. 페치 함수가 호출되기 전에 SQL_ADD 연산이 있는 SQLBulkOperations 가 호출되는 경우에도 사용되지 않습니다. 즉, 문 상태 S7에서만 사용됩니다. 문 상태 S5 또는 S6에는 사용되지 않습니다. 자세한 내용은 부록 B: ODBC 상태 전환 테이블의 문 전환을 참조하세요.
애플리케이션은 RowStatusArray 인수에 유효한 포인터를 제공해야 합니다. 그렇지 않은 경우 SQLExtendedFetch에서 커서를 배치한 후 SQLExtendedFetch의 동작 및 SQLBulkOperations 또는 SQLSetPos에 대한 호출 동작은 정의되지 않습니다.
반품
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR 또는 SQL_INVALID_HANDLE.
진단
SQLExtendedFetch가 SQL_ERROR 또는 SQL_SUCCESS_WITH_INFO 반환하는 경우 SQLError를 호출하여 연결된 SQLSTATE 값을 가져올 수 있습니다. 다음 표에서는 SQLExtendedFetch에서 일반적으로 반환되는 SQLSTATE 값을 나열하고 이 함수의 컨텍스트에서 각 값을 설명합니다. 표기법 "(DM)"은 드라이버 관리자가 반환한 SQLSTATE에 대한 설명 앞에 나와 있습니다. 달리 명시되지 않는 한 각 SQLSTATE 값과 연결된 반환 코드는 SQL_ERROR. 단일 열에서 오류가 발생하면 오류가 발생한 열을 확인하기 위해 SQL_DIAG_COLUMN_NUMBER DiagIdentifier를 사용하여 SQLGetDiagField를 호출할 수 있으며, SQLGetDiagField는 SQL_DIAG_ROW_NUMBER DiagIdentifier를 사용하여 해당 열이 포함된 행을 확인할 수 있습니다.
| SQLSTATE | 오류 | 설명 |
|---|---|---|
| 01000 | 일반 경고 | 드라이버 관련 정보 메시지입니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| 01004 | 문자열 데이터, 오른쪽 잘림 | 열에 대해 반환된 문자열 또는 이진 데이터로 인해 비블랭크 문자 또는 NULL이 아닌 이진 데이터가 잘리게 됩니다. 문자열 값인 경우 오른쪽에서 잘렸습니다. 숫자 값인 경우 숫자의 소수 부분이 잘렸습니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| 01S01 | 행의 오류 | 하나 이상의 행을 가져오는 동안 오류가 발생했습니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| 01S06 | 결과 집합이 첫 번째 행 집합을 반환하기 전에 페치 시도 | 요청된 행 집합은 현재 위치가 첫 번째 행을 초과할 때 결과 집합의 시작 부분과 겹쳐졌으며 FetchOrientation 이 SQL_PRIOR 또는 FetchOrientation 은 절대값이 현재 SQL_ROWSET_SIZE 작거나 같은 음 의 FetchOffset 으로 SQL_RELATIVE. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| 01S07 | 분수 잘림 | 열에 대해 반환된 데이터가 잘렸습니다. 숫자 데이터 형식의 경우 숫자의 소수 부분이 잘렸습니다. 시간, 타임스탬프 및 시간 구성 요소가 포함된 간격 데이터 형식의 경우 시간의 소수 부분이 잘렸습니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| 07006 | 제한된 데이터 형식 특성 위반 | 데이터 값을 SQLBindCol의 TargetType 에서 지정한 C 데이터 형식으로 변환할 수 없습니다. |
| 07009 | 설명자 인덱스가 잘못되었습니다. | 열 0이 SQLBindCol로 바인딩되었고 SQL_ATTR_USE_BOOKMARKS 문 특성이 SQL_UB_OFF 설정되었습니다. |
| 08S01 | 통신 링크 실패 | 드라이버와 드라이버가 연결된 데이터 원본 간의 통신 링크는 함수가 처리를 완료하기 전에 실패했습니다. |
| 22002 | 표시기 변수가 필요하지만 제공되지 않음 | NULL 데이터는 SQLBindCol에서 설정한 StrLen_or_IndPtr null 포인터인 열로 가져왔습니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| 22003 | 숫자 값이 범위를 벗어났습니다. | 하나 이상의 열에 대해 숫자 값(숫자 또는 문자열)을 반환하면 숫자의 전체 부분(소수 부분이 아닌)이 잘렸을 것입니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. 자세한 내용은 부록 D: 데이터 형식의 간격 및 숫자 데이터 형식에 대한 지침을 참조하세요. |
| 22007 | 날짜/시간 형식이 잘못되었습니다. | 결과 집합의 문자 열은 날짜, 시간 또는 타임스탬프 C 구조체에 바인딩되었고 열의 값은 각각 잘못된 날짜, 시간 또는 타임스탬프였습니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| 22012 | 0으로 나누기 | 산술 식의 값이 반환되어 0으로 나누기됩니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| 22015 | 간격 필드 오버플로 | 정확한 숫자 또는 간격 SQL 형식에서 간격 C 형식으로 할당하면 선행 필드에서 상당한 자릿수가 손실되었습니다. 데이터를 간격 C 형식으로 가져올 때 간격 C 형식의 SQL 형식 값에 대한 표현이 없었습니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| 22018 | 캐스트 사양에 잘못된 문자 값 | C 형식은 정확히 또는 근사치 숫자, 날짜/시간 또는 간격 데이터 형식입니다. 열의 SQL 형식은 문자 데이터 형식입니다. 열의 값이 바인딩된 C 형식의 유효한 리터럴이 아니었습니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| 24000 | 커서 상태가 잘못되었습니다. | StatementHandle이 실행된 상태였지만 결과 집합이 StatementHandle과 연결되지 않았습니다. |
| HY000 | 일반 오류 | 특정 SQLSTATE가 없고 구현별 SQLSTATE가 정의되지 않은 오류가 발생했습니다. *MessageText 버퍼의 SQLError에서 반환된 오류 메시지는 오류와 그 원인을 설명합니다. |
| HY001 | 메모리 할당 오류 | 드라이버가 함수 실행 또는 완료를 지원하는 데 필요한 메모리를 할당할 수 없습니다. |
| HY008 | 작업이 취소됨 | StatementHandle에 대해 비동기 처리를 사용하도록 설정했습니다. 함수가 호출되었고 실행이 완료되기 전에 StatementHandle에서 SQLCancel 또는 SQLCancelHandle이 호출된 후 StatementHandle에서 함수가 다시 호출되었습니다. 함수가 호출되었고 실행을 완료하기 전에 다중 스레드 애플리케이션의 다른 스레드에서 StatementHandle에서 SQLCancel 또는 SQLCancelHandle이 호출되었습니다. |
| HY010 | 함수 시퀀스 오류 | (DM) StatementHandle과 연결된 연결 핸들에 대해 비동기적으로 실행되는 함수가 호출되었습니다. 이 비동기 함수는 SQLExtendedFetch 함수가 호출되었을 때 계속 실행되었습니다. (DM) SQLExecute, SQLExecDirect 또는 SQLMoreResults가 StatementHandle에 대해 호출되고 SQL_PARAM_DATA_AVAILABLE 반환되었습니다. 이 함수는 모든 스트리밍된 매개 변수에 대해 데이터를 검색하기 전에 호출되었습니다. (DM) 지정된 StatementHandle 이 실행된 상태가 아닙니다. 이 함수는 먼저 SQLExecDirect, SQLExecute 또는 카탈로그 함수를 호출하지 않고 호출되었습니다. (DM) 이 함수가 아닌 비동기 실행 함수가 StatementHandle에 대해 호출되었고 이 함수가 호출되었을 때 계속 실행되고 있었습니다. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations 또는 SQLSetPos가 StatementHandle에 대해 호출되고 SQL_NEED_DATA 반환되었습니다. 이 함수는 모든 실행 시 데이터 매개 변수 또는 열에 대한 데이터를 보내기 전에 호출되었습니다. (DM) SQLFetch 또는 SQLFetchScroll이 호출된 후 sqlFreeStmt가 SQL_CLOSE 옵션을 사용하여 호출되기 전에 StatementHandle에 대해 SQLExtendedFetch가 호출되었습니다. (DM) SQLFetch, SQLFetchScroll 또는 SQLExtendedFetch가 호출되기 전에 문에 대해 SQLBulkOperations가 호출된 다음 SQLFreeStmt가 SQL_CLOSE 옵션으로 호출되기 전에 SQLExtendedFetch가 호출되었습니다. |
| HY013 | 메모리 관리 오류 | 메모리 조건이 낮기 때문에 기본 메모리 개체에 액세스할 수 없기 때문에 함수 호출을 처리할 수 없습니다. |
| HY106 | 페치 형식이 범위를 벗어났습니다. | (DM) FetchOrientation 인수에 지정된 값이 잘못되었습니다. ("주석"을 참조하세요.) FetchOrientation 인수가 SQL_FETCH_BOOKMARK SQL_ATTR_USE_BOOKMARKS 문 특성이 SQL_UB_OFF 설정되었습니다. SQL_CURSOR_TYPE 문 옵션의 값이 SQL_CURSOR_FORWARD_ONLY 인수 FetchOrientation 값이 SQL_FETCH_NEXT 않았습니다. FetchOrientation 인수가 SQL_FETCH_RESUME. |
| HY107 | 행 값이 범위를 벗어났습니다. | SQL_CURSOR_TYPE 문 옵션으로 지정된 값은 SQL_CURSOR_KEYSET_DRIVEN SQL_KEYSET_SIZE 문 특성으로 지정된 값이 0보다 크고 SQL_ROWSET_SIZE 문 특성으로 지정된 값보다 작습니다. |
| HY111 | 책갈피 값이 잘못되었습니다. | FetchOrientation 인수가 SQL_FETCH_BOOKMARK FetchOffset 인수에 지정된 책갈피가 잘못되었습니다. |
| HY117 | 알 수 없는 트랜잭션 상태로 인해 연결이 일시 중단됩니다. 연결 끊기 및 읽기 전용 함수만 허용됩니다. | (DM) 일시 중단 상태에 대한 자세한 내용은 SQLEndTran 함수를 참조 하세요. |
| HYC00 | 선택적 기능이 구현되지 않음 | 드라이버 또는 데이터 원본은 지정된 인출 형식을 지원하지 않습니다. 드라이버 또는 데이터 원본은 SQLBindCol의 TargetType과 해당 열의 SQL 데이터 형식 조합으로 지정된 변환을 지원하지 않습니다. 이 오류는 열의 SQL 데이터 형식이 드라이버별 SQL 데이터 형식에 매핑된 경우에만 적용됩니다. |
| HYT00 | 시간 제한 만료됨 | 데이터 원본이 결과 집합을 반환하기 전에 쿼리 제한 시간이 만료되었습니다. 시간 제한 기간은 SQL_QUERY_TIMEOUT SQLSetStmtOption을 통해 설정됩니다. |
| HYT01 | 연결 제한 시간이 만료됨 | 데이터 원본이 요청에 응답하기 전에 연결 제한 시간이 만료되었습니다. 연결 제한 시간은 SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr를 통해 설정됩니다. |
| IM001 | 드라이버는 이 함수를 지원하지 않습니다. | (DM) StatementHandle과 연결된 드라이버는 함수를 지원하지 않습니다. |
설명
SQLExtendedFetch의 동작은 다음과 같은 예외를 제외하고 SQLFetchScroll의 동작과 동일합니다.
SQLExtendedFetch 및 SQLFetchScroll 은 다른 메서드를 사용하여 페치된 행 수를 반환합니다. SQLExtendedFetch는 *RowCountPtr에서 가져온 행 수를 반환합니다.SQLFetchScroll은 SQL_ATTR_ROWS_FETCHED_PTR 가리키는 버퍼에 직접 가져온 행 수를 반환합니다. 자세한 내용은 RowCountPtr 인수를 참조하세요.
SQLExtendedFetch 및 SQLFetchScroll 은 서로 다른 배열에 있는 각 행의 상태를 반환합니다. 자세한 내용은 RowStatusArray 인수를 참조하세요.
SQLExtendedFetch 및 SQLFetchScroll은 FetchOrientation이 SQL_FETCH_BOOKMARK 때 다른 메서드를 사용하여 책갈피를 검색합니다. SQLExtendedFetch 는 책갈피에서 0 이외의 오프셋에서 가변 길이 책갈피 또는 행 집합 가져오기를 지원하지 않습니다. 자세한 내용은 FetchOffset 인수를 참조하세요.
SQLExtendedFetch 및 SQLFetchScroll 은 서로 다른 행 집합 크기를 사용합니다. SQLExtendedFetch는 SQL_ROWSET_SIZE 문 특성의 값을 사용하고 SQLFetchScroll 은 SQL_ATTR_ROW_ARRAY_SIZE 문 특성의 값을 사용합니다.
SQLExtendedFetch에는 SQLFetchScroll과 약간 다른 오류 처리 의미 체계가 있습니다. 자세한 내용은 SQLFetchScroll의 "주석" 섹션에서 "오류 처리"를 참조하세요.
SQLExtendedFetch 는 바인딩 오프셋(SQL_ATTR_ROW_BIND_OFFSET_PTR 문 특성)을 지원하지 않습니다.
SQLExtendedFetch에 대한 호출은 SQLFetch 또는 SQLFetchScroll 호출과 혼합할 수 없으며, 인출 함수가 호출되기 전에 SQLBulkOperations가 호출되면 커서가 닫히고 다시 열릴 때까지 SQLExtendedFetch를 호출할 수 없습니다. 즉, SQLExtendedFetch 는 문 상태 S7에서만 호출할 수 있습니다. 자세한 내용은 부록 B: ODBC 상태 전환 테이블의 문 전환을 참조하세요.
애플리케이션이 ODBC 2*.x* 드라이버를 사용하는 동안 SQLFetchScroll을 호출하면 드라이버 관리자는 이 호출을 SQLExtendedFetch에 매핑합니다. 자세한 내용은 SQLFetchScroll의 "SQLFetchScroll 및 ODBC 2*.x* 드라이버"를 참조하세요.
ODBC 2*.x* 에서 SQLExtendedFetch 는 여러 행을 가져오기 위해 호출되었고 SQLFetch 는 단일 행을 가져오기 위해 호출되었습니다. 반면 ODBC 3*.x*에서는 SQLFetch 를 호출하여 여러 행을 가져올 수 있습니다.
관련 함수
| 추가 정보 | 참조 |
|---|---|
| 결과 집합의 열에 버퍼 바인딩 | SQLBindCol 함수 |
| 대량 삽입, 업데이트 또는 삭제 작업 수행 | SQLBulkOperations 함수 |
| 문 처리 취소 | SQLCancel 함수 |
| 결과 집합의 열에 대한 정보 반환 | SQLDescribeCol 함수 |
| SQL 문 실행 | SQLExecDirect 함수 |
| 준비된 SQL 문 실행 | SQLExecute 함수 |
| 결과 집합 열 수 반환 | SQLNumResultCols 함수 |
| 커서 위치 지정, 행 집합의 데이터 새로 고침 또는 결과 집합의 데이터 업데이트 또는 삭제 | SQLSetPos 함수 |
| 문 특성 설정 | SQLSetStmtAttr 함수 |