SQLFetchScroll 함수(SQLFetchScroll Function)

규칙
도입된 버전: ODBC 3.0 표준 준수: ISO 92

요약
SQLFetchScroll 은 결과 집합에서 지정된 데이터 행 집합을 가져오고 모든 바인딩된 열에 대한 데이터를 반환합니다. 행 집합은 절대 또는 상대 위치 또는 책갈피로 지정할 수 있습니다.

ODBC 2.x 드라이버로 작업할 때 드라이버 관리자는 이 함수를 SQLExtendedFetch에 매핑합니다. 자세한 내용은 애플리케이션의 이전 버전과의 호환성을 위한 대체 함수 매핑을 참조 하세요.

구문

  
SQLRETURN SQLFetchScroll(  
      SQLHSTMT      StatementHandle,  
      SQLSMALLINT   FetchOrientation,  
      SQLLEN        FetchOffset);  

인수

StatementHandle
[입력] 문 핸들입니다.

FetchOrientation
[입력]

인출 유형:

SQL_FETCH_NEXT

SQL_FETCH_PRIOR

SQL_FETCH_FIRST

SQL_FETCH_LAST

SQL_FETCH_ABSOLUTE

SQL_FETCH_RELATIVE

SQL_FETCH_BOOKMARK

자세한 내용은 "메모" 섹션에서 "커서 위치 지정"을 참조하세요.

FetchOffset
[입력]

가져올 행의 수입니다. 이 인수의 해석은 FetchOrientation 인수의 값에 따라 달라집니다. 자세한 내용은 "메모" 섹션에서 "커서 위치 지정"을 참조하세요.

반품

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR 또는 SQL_INVALID_HANDLE.

진단

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

SQL_SUCCESS_WITH_INFO 또는 SQL_ERROR 반환할 수 있는 모든 SQLSTATE의 경우(01xxx SQLSTATE 제외) SQL_SUCCESS_WITH_INFO 다중 행 작업의 행 중 하나 이상에서 오류가 발생하는 경우 반환되고 단일 행 작업에서 오류가 발생하면 SQL_ERROR 반환됩니다.

SQLSTATE	오류	설명
01000	일반 경고	드라이버 관련 정보 메시지입니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다.
01004	문자열 데이터, 오른쪽 잘림	열에 대해 반환된 문자열 또는 이진 데이터로 인해 비블랭크 문자 또는 NULL이 아닌 이진 데이터가 잘리게 됩니다. 문자열 값인 경우 오른쪽에서 잘렸습니다.
01S01	행의 오류	하나 이상의 행을 가져오는 동안 오류가 발생했습니다. (ODBC 3*.x* 애플리케이션이 ODBC 2*.x* 드라이버로 작업할 때 이 SQLSTATE가 반환되는 경우 무시될 수 있습니다.)
01S06	결과 집합이 첫 번째 행 집합을 반환하기 전에 페치 시도	요청된 행 집합은 FetchOrientation이 SQL_FETCH_PRIOR 때 결과 집합의 시작 부분과 겹치고, 현재 위치가 첫 번째 행을 벗어나고, 현재 행의 수가 행 집합 크기보다 작거나 같을 때 겹칩니다. FetchOrientation이 SQL_FETCH_PRIOR 때 요청된 행 집합이 결과 집합의 시작 부분과 겹치고, 현재 위치가 결과 집합의 끝을 벗어나고, 행 집합 크기가 결과 집합 크기보다 큽니다. 요청한 행 집합은 FetchOrientation이 SQL_FETCH_RELATIVE, FetchOffset이 음수이고, FetchOffset의 절대 값이 행 집합 크기보다 작거나 같을 때 결과 집합의 시작 부분과 겹칩니다. 요청된 행 집합은 FetchOrientation이 SQL_FETCH_ABSOLUTE, FetchOffset이 음수이고, FetchOffset의 절대값이 결과 집합 크기보다 크지만 행 집합 크기보다 작거나 같을 때 결과 집합의 시작 부분과 겹칩니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다.
01S07	분수 잘림	열에 대해 반환된 데이터가 잘렸습니다. 숫자 데이터 형식의 경우 숫자의 소수 부분이 잘렸습니다. 시간, 타임스탬프 및 시간 구성 요소가 포함된 간격 데이터 형식의 경우 시간의 소수 부분이 잘렸습니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다.
07006	제한된 데이터 형식 특성 위반	결과 집합에 있는 열의 데이터 값을 SQLBindCol의 TargetType 에 지정된 데이터 형식으로 변환할 수 없습니다. 열 0은 데이터 형식의 SQL_C_BOOKMARK 바인딩되었으며 SQL_ATTR_USE_BOOKMARKS 문 특성은 SQL_UB_VARIABLE 설정되었습니다. 열 0은 데이터 형식의 SQL_C_VARBOOKMARK 바인딩되었으며 SQL_ATTR_USE_BOOKMARKS 문 특성이 SQL_UB_VARIABLE 설정되지 않았습니다.
07009	설명자 인덱스가 잘못되었습니다.	드라이버는 SQLExtendedFetch를 지원하지 않는 ODBC 2*.x* 드라이버이고 열에 대한 바인딩에 지정된 열 번호는 0입니다. 열 0이 바인딩되었고 SQL_ATTR_USE_BOOKMARKS 문 특성이 SQL_UB_OFF 설정되었습니다.
08S01	통신 링크 실패	드라이버와 드라이버가 연결된 데이터 원본 간의 통신 링크는 함수가 처리를 완료하기 전에 실패했습니다.
22001	문자열 데이터, 오른쪽 잘림	열에 대해 반환된 가변 길이 책갈피가 잘렸습니다.
22002	표시기 변수가 필요하지만 제공되지 않음	NULL 데이터는 SQLBindCol에서 설정한 StrLen_or_IndPtr(또는 SQLSetDescField 또는 SQLSetDescRec에서 설정한 SQL_DESC_INDICATOR_PTR)이 null 포인터인 열로 가져왔습니다.
22003	숫자 값이 범위를 벗어났습니다.	하나 이상의 바인딩된 열에 대해 숫자 값(숫자 또는 문자열)을 반환하면 숫자의 전체 부분(소수 부분이 아닌)이 잘렸을 것입니다. 자세한 내용은 부록 D: 데이터 형식의 SQL에서 C 데이터 형식으로 데이터 변환을 참조하세요.
22007	날짜/시간 형식이 잘못되었습니다.	결과 집합의 문자 열은 날짜, 시간 또는 타임스탬프 C 구조체에 바인딩되었고 열의 값은 각각 잘못된 날짜, 시간 또는 타임스탬프였습니다.
22012	0으로 나누기	산술 식의 값이 반환되어 0으로 나누기됩니다.
22015	간격 필드 오버플로	정확한 숫자 또는 간격 SQL 형식에서 간격 C 형식으로 할당하면 선행 필드에서 상당한 자릿수가 손실되었습니다. 데이터를 간격 C 형식으로 가져올 때 간격 C 형식의 SQL 형식 값에 대한 표현이 없었습니다.
22018	캐스트 사양에 잘못된 문자 값	결과 집합의 문자 열이 문자 C 버퍼에 바인딩되었고 열에 버퍼의 문자 집합에 표현이 없는 문자가 포함되었습니다. C 형식은 정확히 또는 근사치 숫자, 날짜/시간 또는 간격 데이터 형식입니다. 열의 SQL 형식은 문자 데이터 형식입니다. 열의 값이 바인딩된 C 형식의 유효한 리터럴이 아니었습니다.
24000	커서 상태가 잘못되었습니다.	StatementHandle이 실행된 상태였지만 결과 집합이 StatementHandle과 연결되지 않았습니다.
40001	Serialization 실패	교착 상태를 방지하기 위해 인출이 실행된 트랜잭션이 종료되었습니다.
40003	문 완성을 알 수 없음	이 함수를 실행하는 동안 연결된 연결이 실패했으며 트랜잭션 상태를 확인할 수 없습니다.
HY000	일반 오류	특정 SQLSTATE가 없고 구현별 SQLSTATE가 정의되지 않은 오류가 발생했습니다. *MessageText 버퍼의 SQLGetDiagRec에서 반환된 오류 메시지는 오류와 그 원인을 설명합니다.
HY001	메모리 할당 오류	드라이버가 함수 실행 또는 완료를 지원하는 데 필요한 메모리를 할당할 수 없습니다.
HY008	작업이 취소됨	StatementHandle에 대해 비동기 처리를 사용하도록 설정했습니다. 함수가 호출되었고 실행이 완료되기 전에 StatementHandle에서 SQLCancel 또는 SQLCancelHandle이 호출되었습니다. 그런 다음 StatementHandle에서 함수가 다시 호출되었습니다. 함수가 호출되었고 실행을 완료하기 전에 다중 스레드 애플리케이션의 다른 스레드에서 StatementHandle에서 SQLCancel 또는 SQLCancelHandle이 호출되었습니다.
HY010	함수 시퀀스 오류	(DM) StatementHandle과 연결된 연결 핸들에 대해 비동기적으로 실행되는 함수가 호출되었습니다. 이 비동기 함수는 SQLFetchScroll 함수가 호출되었을 때 계속 실행되고 있었습니다. (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) SQLExtendedFetch가 호출된 후 및 SQL_CLOSE 옵션을 사용하여 SQLFreeStmt가 호출되기 전에 StatementHandle에 대해 SQLFetch가 호출되었습니다.
HY013	메모리 관리 오류	메모리 조건이 낮기 때문에 기본 메모리 개체에 액세스할 수 없기 때문에 함수 호출을 처리할 수 없습니다.
HY090	잘못된 문자열 또는 버퍼 길이	SQL_ATTR_USE_BOOKMARK 문 특성이 SQL_UB_VARIABLE 설정되었고, 열 0은 길이가 이 결과 집합의 책갈피의 최대 길이와 같지 않은 버퍼에 바인딩되었습니다. (이 길이는 IRD의 SQL_DESC_OCTET_LENGTH 필드에서 사용할 수 있으며 호출 하여 가져올 수 있습니다.SQLDescribeCol, SQLColAttribute 또는 SQLGetDescField.)
HY106	페치 형식이 범위를 벗어났습니다.	DM) FetchOrientation 인수에 지정된 값이 잘못되었습니다. (DM) FetchOrientation 인수가 SQL_FETCH_BOOKMARK SQL_ATTR_USE_BOOKMARKS 문 특성이 SQL_UB_OFF 설정되었습니다. SQL_ATTR_CURSOR_TYPE 문 특성의 값이 SQL_CURSOR_FORWARD_ONLY 인수 FetchOrientation 값이 SQL_FETCH_NEXT 않았습니다. SQL_ATTR_CURSOR_SCROLLABLE 문 특성의 값이 SQL_NONSCROLLABLE 인수 FetchOrientation 값이 SQL_FETCH_NEXT 않았습니다.
HY107	행 값이 범위를 벗어났습니다.	SQL_ATTR_CURSOR_TYPE 문 특성으로 지정된 값은 SQL_CURSOR_KEYSET_DRIVEN SQL_ATTR_KEYSET_SIZE 문 특성으로 지정된 값이 0보다 크고 SQL_ATTR_ROW_ARRAY_SIZE 문 특성으로 지정된 값보다 작습니다.
HY111	책갈피 값이 잘못되었습니다.	FetchOrientation 인수가 SQL_FETCH_BOOKMARK SQL_ATTR_FETCH_BOOKMARK_PTR 문 특성의 값이 가리키는 책갈피가 잘못되었거나 null 포인터였습니다.
HY117	알 수 없는 트랜잭션 상태로 인해 연결이 일시 중단됩니다. 연결 끊기 및 읽기 전용 함수만 허용됩니다.	(DM) 일시 중단 상태에 대한 자세한 내용은 SQLEndTran 함수를 참조 하세요.
HYC00	선택적 기능이 구현되지 않음	드라이버 또는 데이터 원본은 SQLBindCol의 TargetType과 해당 열의 SQL 데이터 형식 조합으로 지정된 변환을 지원하지 않습니다.
HYT00	시간 제한 만료됨	데이터 원본이 요청된 결과 집합을 반환하기 전에 쿼리 제한 시간이 만료되었습니다. 제한 시간은 SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT 통해 설정됩니다.
HYT01	연결 제한 시간이 만료됨	데이터 원본이 요청에 응답하기 전에 연결 제한 시간이 만료되었습니다. 연결 제한 시간은 SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr를 통해 설정됩니다.
IM001	드라이버는 이 함수를 지원하지 않습니다.	(DM) StatementHandle과 연결된 드라이버는 함수를 지원하지 않습니다.
IM017	비동기 알림 모드에서 폴링을 사용할 수 없습니다.	알림 모델을 사용할 때마다 폴링이 비활성화됩니다.
IM018	이 핸들에서 이전 비동기 작업을 완료하기 위해 SQLCompleteAsync 가 호출되지 않았습니다.	핸들의 이전 함수 호출이 SQL_STILL_EXECUTING 반환하고 알림 모드가 활성화된 경우 사후 처리를 수행하고 작업을 완료하려면 핸들에서 SQLCompleteAsync 를 호출해야 합니다.

설명

SQLFetchScroll 은 결과 집합에서 지정된 행 집합을 반환합니다. 행 집합은 절대 또는 상대 위치 또는 책갈피로 지정할 수 있습니다. 결과 집합이 존재하는 경우에만 SQLFetchScroll 을 호출할 수 있습니다. 즉, 결과 집합을 만드는 호출 후 및 결과 집합에 대한 커서가 닫혀 있기 전에 호출할 수 있습니다. 열이 바인딩된 경우 해당 열의 데이터를 반환합니다. 애플리케이션이 가져온 행 수를 반환할 행 상태 배열 또는 버퍼에 대한 포인터를 지정한 경우 SQLFetchScroll 도 이 정보를 반환합니다. SQLFetchScroll에 대한 호출은 SQLFetch 호출과 혼합될 수 있지만 SQLExtendedFetch 호출과 혼합할 수는 없습니다.

자세한 내용은 블록 커서 사용 및 스크롤 가능한 커서 사용을 참조하세요.

커서 위치 지정

결과 집합을 만들면 결과 집합이 시작되기 전에 커서가 배치됩니다. SQLFetchScroll은 다음 표와 같이 FetchOrientation 및 FetchOffset 인수의 값에 따라 블록 커서의 위치를 지정합니다. 새 행 집합의 시작을 결정하는 정확한 규칙은 다음 섹션에 나와 있습니다.

FetchOrientation	의미
SQL_FETCH_NEXT	다음 행 집합을 반환합니다. 이는 SQLFetch를 호출하는 것과 같습니다. SQLFetchScroll은 FetchOffset의 값을 무시합니다.
SQL_FETCH_PRIOR	이전 행 집합을 반환합니다. SQLFetchScroll은 FetchOffset의 값을 무시합니다.
SQL_FETCH_RELATIVE	현재 행 집합의 시작 부분에서 행 집합 FetchOffset 을 반환합니다.
SQL_FETCH_ABSOLUTE	행 FetchOffset에서 시작하는 행 집합을 반환합니다.
SQL_FETCH_FIRST	결과 집합의 첫 번째 행 집합을 반환합니다. SQLFetchScroll은 FetchOffset의 값을 무시합니다.
SQL_FETCH_LAST	결과 집합의 마지막 전체 행 집합을 반환합니다. SQLFetchScroll은 FetchOffset의 값을 무시합니다.
SQL_FETCH_BOOKMARK	SQL_ATTR_FETCH_BOOKMARK_PTR 문 특성에 지정된 책갈피에서 행 집합 FetchOffset 행을 반환합니다.

드라이버는 모든 페치 방향을 지원할 필요가 없습니다. 애플리케이션은 SQL_DYNAMIC_CURSOR_ATTRIBUTES1, SQL_KEYSET_CURSOR_ATTRIBUTES1 또는 SQL_STATIC_CURSOR_ATTRIBUTES1 정보 유형(커서 유형에 따라 다름)을 사용하여 SQLGetInfo를 호출하여 드라이버에서 지원하는 페치 방향을 결정합니다. 애플리케이션은 이러한 정보 형식의 SQL_CA1_NEXT, SQL_CA1_RELATIVE, SQL_CA1_ABSOLUTE 및 WQL_CA1_BOOKMARK 비트 마스크를 확인해야 합니다. 또한 커서가 정방향 전용이고 FetchOrientation이 SQL_FETCH_NEXT 않으면 SQLFetchScroll 은 SQLSTATE HY106(Fetch 형식이 범위를 벗어났습니다)을 반환합니다.

SQL_ATTR_ROW_ARRAY_SIZE 문 특성은 행 집합의 행 수를 지정합니다. SQLFetchScroll에서 가져오는 행 집합이 결과 집합의 끝 부분과 겹치면 SQLFetchScroll은 부분 행 집합을 반환합니다. 즉, S + R - 1이 L보다 크면 S가 페치되는 행 집합의 시작 행이고 R은 행 집합 크기이고 L은 결과 집합의 마지막 행인 경우 행 집합의 첫 번째 L - S + 1 행만 유효합니다. 나머지 행은 비어 있으며 상태가 SQL_ROW_NOROW.

SQLFetchScroll이 반환된 후 현재 행은 행 집합의 첫 번째 행입니다.

커서 위치 지정 규칙

다음 섹션에서는 FetchOrientation의 각 값에 대한 정확한 규칙을 설명합니다. 이러한 규칙은 다음 표기법을 사용합니다.

Notation	의미
시작하기 전	블록 커서는 결과 집합이 시작되기 전에 배치됩니다. 새 행 집합의 첫 번째 행이 결과 집합 의 시작 전인 경우 SQLFetchScroll 은 SQL_NO_DATA 반환합니다.
종료 후	블록 커서는 결과 집합의 끝 뒤에 배치됩니다. 새 행 집합의 첫 번째 행이 결과 집합 의 끝 이후이면 SQLFetchScroll 은 SQL_NO_DATA 반환합니다.
CurrRowsetStart	현재 행 집합의 첫 번째 행 수입니다.
LastResultRow	결과 집합의 마지막 행 수입니다.
RowsetSize	행 집합 크기입니다.
FetchOffset	FetchOffset 인수의 값입니다 .
BookmarkRow	SQL_ATTR_FETCH_BOOKMARK_PTR 문 특성에 지정된 책갈피에 해당하는 행입니다.

SQL_FETCH_NEXT

다음 규칙이 적용됩니다.

조건	새 행 집합의 첫 번째 행
시작하기 전	1
CurrRowsetStart + RowsetSize[1] <= LastResultRow	CurrRowsetStart + RowsetSize[1]
CurrRowsetStart + RowsetSize[1]> LastResultRow	종료 후
종료 후	종료 후

[1] 행 가져오기에 대한 이전 호출 이후 행 집합 크기가 변경된 경우 이전 호출에 사용된 행 집합 크기입니다.

SQL_FETCH_PRIOR

다음 규칙이 적용됩니다.

조건	새 행 집합의 첫 번째 행
시작하기 전	시작하기 전
CurrRowsetStart = 1	시작하기 전
1 < CurrRowsetStart <= RowsetSize [2]	1 [1]
CurrRowsetStart > RowsetSize [2]	CurrRowsetStart - RowsetSize [2]
After end AND LastResultRow < RowsetSize [2]	1 [1]
After end AND LastResultRow >= RowsetSize [2]	LastResultRow - RowsetSize + 1 [2]

[1] SQLFetchScroll 은 SQLSTATE 01S06(결과 집합이 첫 번째 행 집합을 반환하기 전에 페치 시도)를 반환하고 SQL_SUCCESS_WITH_INFO.

[2] 행 가져오기에 대한 이전 호출 이후 행 집합 크기가 변경된 경우 새 행 집합 크기입니다.

SQL_FETCH_RELATIVE

다음 규칙이 적용됩니다.

조건	새 행 집합의 첫 번째 행
(시작 전 및 FetchOffset > 0) 또는 (After end and FetchOffset < 0)	--[1]
BeforeStart and FetchOffset <= 0	시작하기 전
CurrRowsetStart = 1 AND FetchOffset < 0	시작하기 전
CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND | FetchOffset | > RowsetSize [3]	시작하기 전
CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND | FetchOffset | <= RowsetSize [3]	1 [2]
1 <= CurrRowsetStart + FetchOffset <= LastResultRow	CurrRowsetStart + FetchOffset
CurrRowsetStart + FetchOffset > LastResultRow	종료 후
종료 후 AND FetchOffset >= 0	종료 후

[1] SQLFetchScroll 은 fetchOrientation이 SQL_FETCH_ABSOLUTE 설정된 상태에서 호출된 것과 동일한 행 집합을 반환합니다. 자세한 내용은 "SQL_FETCH_ABSOLUTE" 섹션을 참조하세요.

[2] SQLFetchScroll 은 SQLSTATE 01S06(결과 집합이 첫 번째 행 집합을 반환하기 전에 인출 시도)을 반환하고 SQL_SUCCESS_WITH_INFO.

[3] 행 가져오기에 대한 이전 호출 이후 행 집합 크기가 변경된 경우 새 행 집합 크기입니다.

SQL_FETCH_ABSOLUTE

다음 규칙이 적용됩니다.

조건	새 행 집합의 첫 번째 행
FetchOffset < 0 AND | FetchOffset | <= LastResultRow	LastResultRow + FetchOffset + 1
FetchOffset < 0 AND | FetchOffset | > LastResultRow AND | FetchOffset | > RowsetSize [2]	시작하기 전
FetchOffset < 0 AND | FetchOffset | > LastResultRow AND | FetchOffset | <= RowsetSize [2]	1 [1]
FetchOffset = 0	시작하기 전
1 <= FetchOffset <= LastResultRow	FetchOffset
FetchOffset > LastResultRow	종료 후

[1] SQLFetchScroll 은 SQLSTATE 01S06(결과 집합이 첫 번째 행 집합을 반환하기 전에 페치 시도)를 반환하고 SQL_SUCCESS_WITH_INFO.

[2] 행 가져오기에 대한 이전 호출 이후 행 집합 크기가 변경된 경우 새 행 집합 크기입니다.

동적 커서에 대해 수행된 절대 인출은 동적 커서의 행 위치가 결정되지 않으므로 필요한 결과를 제공할 수 없습니다. 이러한 작업은 페치 다음에 페치 상대가 오는 것과 같습니다. 정적 커서의 절대 인출처럼 원자성 연산이 아닙니다.

SQL_FETCH_FIRST

다음 규칙이 적용됩니다.

조건	새 행 집합의 첫 번째 행
모두	1

SQL_FETCH_LAST

다음 규칙이 적용됩니다.

조건	새 행 집합의 첫 번째 행
RowsetSize [1]<= LastResultRow	LastResultRow - RowsetSize + 1 [1]
RowsetSize [1]> LastResultRow	1

[1] 행 가져오기에 대한 이전 호출 이후 행 집합 크기가 변경된 경우 새 행 집합 크기입니다.

SQL_FETCH_BOOKMARK

다음 규칙이 적용됩니다.

조건	새 행 집합의 첫 번째 행
BookmarkRow + FetchOffset < 1	시작하기 전
1 <= BookmarkRow + FetchOffset <= LastResultRow	BookmarkRow + FetchOffset
BookmarkRow + FetchOffset > LastResultRow	종료 후

책갈피에 대한 자세한 내용은 책갈피(ODBC)를 참조하세요.

커서 이동에 대한 삭제됨, 추가됨 및 오류 행의 효과

정적 및 키 집합 기반 커서는 때때로 결과 집합에 추가된 행을 검색하고 결과 집합에서 삭제된 행을 제거합니다. SQL_STATIC_CURSOR_ATTRIBUTES2 및 SQL_KEYSET_CURSOR_ATTRIBUTES2 옵션을 사용하여 SQLGetInfo를 호출하고 SQL_CA2_SENSITIVITY_ADDITIONS, SQL_CA2_SENSITIVITY_DELETIONS 및 SQL_CA2_SENSITIVITY_UPDATES 비트 마스크를 확인하여 애플리케이션은 특정 드라이버에서 구현된 커서가 이 작업을 수행하는지 여부를 결정합니다. 삭제된 행을 검색하고 제거할 수 있는 드라이버의 경우 다음 단락에서 이 동작의 영향을 설명합니다. 삭제된 행을 검색할 수 있지만 제거할 수 없는 드라이버의 경우 삭제는 커서 이동에 영향을 주지 않으며 다음 단락은 적용되지 않습니다.

커서가 결과 집합에 추가된 행을 검색하거나 결과 집합에서 삭제된 행을 제거하면 데이터를 가져올 때만 이러한 변경 내용을 감지하는 것처럼 표시됩니다. 여기에는 동일한 행 집합을 다시 페치하기 위해 fetchOrientation이 SQL_FETCH_RELATIVE 설정되고 FetchOffset이 0으로 설정된 상태에서 SQLFetchScroll이 호출되는 경우를 포함하지만 SQL_REFRESH fOption 집합을 사용하여 SQLSetPos가 호출되는 경우는 포함되지 않습니다. 후자의 경우 행 집합 버퍼의 데이터는 새로 고쳐지지만 다시 적용되지 않으며 삭제된 행은 결과 집합에서 제거되지 않습니다. 따라서 행을 삭제하거나 현재 행 집합에 삽입할 때 커서는 행 집합 버퍼를 수정하지 않습니다. 대신 이전에 삭제된 행을 포함하거나 삽입된 행을 포함하는 행 집합을 가져올 때 변경 내용을 감지합니다.

예시:

// Fetch the next rowset.  
SQLFetchScroll(hstmt, SQL_FETCH_NEXT, 0);  
// Delete third row of the rowset. Does not modify the rowset buffers.  
SQLSetPos(hstmt, 3, SQL_DELETE, SQL_LOCK_NO_CHANGE);  
// The third row has a status of SQL_ROW_DELETED after this call.  
SQLSetPos(hstmt, 3, SQL_REFRESH, SQL_LOCK_NO_CHANGE);  
// Refetch the same rowset. The third row is removed, replaced by what  
// was previously the fourth row.  
SQLFetchScroll(hstmt, SQL_FETCH_RELATIVE, 0);  

SQLFetchScroll은 현재 행 집합을 기준으로 하는 위치가 있는 새 행 집합을 반환합니다. 즉, FetchOrientation이 SQL_FETCH_NEXT, SQL_FETCH_PRIOR 또는 SQL_FETCH_RELATIVE 경우 새 행 집합의 시작 위치를 계산할 때 현재 행 집합에 대한 변경 내용은 포함되지 않습니다. 그러나 검색할 수 있는 경우 현재 행 집합 외부의 변경 내용이 포함됩니다. 또한 SQLFetchScroll 이 현재 행 집합과 독립적인 위치가 있는 새 행 집합을 반환하는 경우, 즉 FetchOrientation이 SQL_FETCH_FIRST, SQL_FETCH_LAST, SQL_FETCH_ABSOLUTE 또는 SQL_FETCH_BOOKMARK 경우 현재 행 집합에 있더라도 검색할 수 있는 모든 변경 내용이 포함됩니다.

새로 추가된 행이 현재 행 집합 내부 또는 외부에 있는지 여부를 결정할 때 부분 행 집합은 마지막 유효한 행에서 끝나는 것으로 간주됩니다. 즉, 행 상태가 SQL_ROW_NOROW 않은 마지막 행입니다. 예를 들어 커서가 새로 추가된 행을 검색할 수 있고, 현재 행 집합이 부분 행 집합이고, 애플리케이션이 새 행을 추가하고, 커서가 이러한 행을 결과 집합의 끝에 추가한다고 가정합니다. 애플리케이션에서 FetchOrientation이 SQL_FETCH_NEXT 설정된 SQLFetchScroll을 호출하는 경우 SQLFetchScroll은 새로 추가된 첫 번째 행부터 행 집합을 반환합니다.

예를 들어 현재 행 집합이 21~30행으로 구성되고, 행 집합 크기가 10이고, 커서가 결과 집합에서 삭제된 행을 제거하고, 커서가 결과 집합에 추가된 행을 검색한다고 가정합니다. 다음 표에서는 다양한 상황에서 SQLFetchScroll이 반환하는 행을 보여 줍니다.

변경	페치 형식	FetchOffset	새 행 집합[1]
행 21 삭제	NEXT	0	31~40
행 31 삭제	NEXT	0	32-41
행 21과 22 사이에 행 삽입	NEXT	0	31~40
행 30과 31 사이에 행 삽입	NEXT	0	삽입된 행, 31-39
행 21 삭제	PRIOR	0	11~20
행 20 삭제	PRIOR	0	10~19명
행 21과 22 사이에 행 삽입	PRIOR	0	11~20
행 20과 21 사이에 행 삽입	PRIOR	0	12~20개, 삽입된 행
행 21 삭제	상대	0	22~31[2]
행 21 삭제	상대	1	22-31
행 21과 22 사이에 행 삽입	상대	0	21, 삽입된 행, 22-29
행 21과 22 사이에 행 삽입	상대	1	22-31
행 21 삭제	절대의	21	22~31[2]
행 22 삭제	절대의	21	21, 23~ 31
행 21과 22 사이에 행 삽입	절대의	22	삽입된 행, 22-29

[1] 이 열은 행을 삽입하거나 삭제하기 전에 행 번호를 사용합니다.

[2] 이 경우 커서는 행 21부터 행을 반환하려고 시도합니다. 행 21이 삭제되었으므로 반환하는 첫 번째 행은 22행입니다.

오류 행(즉, 상태가 SQL_ROW_ERROR 행)은 커서 이동에 영향을 미치지 않습니다. 예를 들어 현재 행 집합이 행 11로 시작되고 행 11의 상태가 SQL_ROW_ERROR 경우 FetchOrientation이 SQL_FETCH_RELATIVE 설정되고 FetchOffset이 5로 설정된 SQLFetchScroll을 호출하면 행 11의 상태가 SQL_SUCCESS 경우와 마찬가지로 16행부터 시작하는 행 집합이 반환됩니다.

바인딩된 열에서 데이터 반환

SQLFetchScroll은 SQLFetch와 동일한 방식으로 바인딩된 열의 데이터를 반환합니다. 자세한 내용은 SQLFetch 함수의 "바인딩된 열에서 데이터 반환"을 참조하세요.

바인딩 된 열이 없는 경우 SQLFetchScroll 은 데이터를 반환하지 않고 블록 커서를 지정된 위치로 이동합니다. SQLGetData를 사용하여 블록 커서의 언바운드 열에서 데이터를 검색할 수 있는지 여부는 드라이버에 따라 달라집니다. 이 기능은 SQLGetInfo 호출이 SQL_GETDATA_EXTENSIONS 정보 유형에 대한 SQL_GD_BLOCK 비트를 반환하는 경우 지원됩니다.

버퍼 주소

SQLFetchScroll은 동일한 수식을 사용하여 SQLFetch와 같은 데이터 주소 및 길이/표시기 버퍼를 결정합니다. 자세한 내용은 SQLBindCol 함수의 "버퍼 주소"를 참조하세요.

행 상태 배열

SQLFetchScroll 은 행 상태 배열의 값을 SQLFetch와 동일한 방식으로 설정합니다. 자세한 내용은 SQLFetch 함수의 "행 상태 배열"을 참조하세요.

가져온 행 버퍼

SQLFetchScroll은 SQLFetch와 동일한 방식으로 페치된 행 버퍼에서 가져온 행 수를 반환합니다. 자세한 내용은 SQLFetch 함수의 "행 페치 버퍼"를 참조하세요.

오류 처리

애플리케이션이 ODBC 3.x 드라이버에서 SQLFetchScroll을 호출하는 경우 드라이버 관리자는 드라이버에서 SQLFetchScroll을 호출 합니다. 애플리케이션이 ODBC 2.x 드라이버에서 SQLFetchScroll을 호출하는 경우 드라이버 관리자는 드라이버에서 SQLExtendedFetch를 호출합니다. SQLFetchScroll 및 SQLExtendedFetch는 약간 다른 방식으로 오류를 처리하므로 애플리케이션은 ODBC 2.x 및 ODBC 3.x 드라이버에서 SQLFetchScroll을 호출할 때 약간 다른 오류 동작을 볼 수 있습니다.

SQLFetchScroll은 SQLFetch와 동일한 방식으로 오류 및 경고를 반환합니다. 자세한 내용은 SQLFetch의 "오류 처리"를 참조하세요. SQLExtendedFetch는 다음과 같은 예외를 제외하고 SQLFetch와 동일한 방식으로 오류를 반환합니다.

행 집합의 특정 행에 적용되는 경고가 발생하면 SQLExtendedFetch는 행 상태 배열의 해당 항목을 SQL_ROW_SUCCESS_WITH_INFO 아닌 SQL_ROW_SUCCESS 설정합니다.

행 집합의 모든 행에서 오류가 발생하면 SQLExtendedFetch는 SQL_ERROR 아닌 SQL_SUCCESS_WITH_INFO 반환합니다.

개별 행에 적용되는 각 상태 레코드 그룹에서 SQLExtendedFetch에서 반환된 첫 번째 상태 레코드에는 SQLSTATE 01S01(행의 오류)이 포함되어야 합니다. SQLFetchScroll 은 이 SQLSTATE를 반환하지 않습니다. SQLExtendedFetch가 추가 SQLSTATE를 반환할 수 없는 경우에도 이 SQLSTATE를 반환해야 합니다.

SQLFetchScroll 및 낙관적 동시성

커서가 낙관적 동시성을 사용하는 경우( 즉, SQL_ATTR_CONCURRENCY 문 특성의 값이 SQL_CONCUR_VALUES 또는 SQL_CONCUR_ROWVER) SQLFetchScroll 은 데이터 원본에서 사용하는 낙관적 동시성 값을 업데이트하여 행이 변경되었는지 여부를 검색합니다. 이 문제는 SQLFetchScroll이 현재 행 집합을 다시 집합할 때를 포함하여 새 행 집합을 가져올 때마다 발생합니다. (FetchOrientation이 SQL_FETCH_RELATIVE 설정되고 FetchOffset이 0으로 설정된 상태에서 호출됩니다.)

SQLFetchScroll 및 ODBC 2.x 드라이버

애플리케이션이 ODBC 2.x 드라이버에서 SQLFetchScroll을 호출하는 경우 드라이버 관리자는 이 호출을 SQLExtendedFetch에 매핑합니다. SQLExtendedFetch의 인수에 대해 다음 값을 전달합니다.

SQLExtendedFetch 인수	값
StatementHandle	SQLFetchScroll의 StatementHandle입니다.
FetchOrientation	SQLFetchScroll의 FetchOrientation입니다.
FetchOffset	FetchOrientation이 SQL_FETCH_BOOKMARK 않으면 SQLFetchScroll의 FetchOffset 인수 값이 사용됩니다. FetchOrientation이 SQL_FETCH_BOOKMARK 경우 SQL_ATTR_FETCH_BOOKMARK_PTR 문 특성으로 지정된 주소에 저장된 값이 사용됩니다.
RowCountPtr	SQL_ATTR_ROWS_FETCHED_PTR 문 특성으로 지정된 주소입니다.
RowStatusArray	SQL_ATTR_ROW_STATUS_PTR 문 특성으로 지정된 주소입니다.

자세한 내용은 부록 G: 이전 버전과의 호환성을 위한 드라이버 지침의 블록 커서, 스크롤 가능한 커서 및 이전 버전과의 호환성을 참조하세요.

설명자 및 SQLFetchScroll

SQLFetchScroll은 SQLFetch와 동일한 방식으로 설명자와 상호 작용합니다. 자세한 내용은 SQLFetch 함수의 "설명자 및 SQLFetchScroll" 섹션 을 참조하세요.

코드 예

SQLSetPos를 사용하여 행 집합에서 열 단위 바인딩, 행 단위 바인딩, 위치 지정 업데이트 및 삭제 문 및 행 업데이트를 참조하세요.

관련 함수

추가 정보	참조
결과 집합의 열에 버퍼 바인딩	SQLBindCol 함수
대량 삽입, 업데이트 또는 삭제 작업 수행	SQLBulkOperations 함수
문 처리 취소	SQLCancel 함수
결과 집합의 열에 대한 정보 반환	SQLDescribeCol 함수
SQL 문 실행	SQLExecDirect 함수
준비된 SQL 문 실행	SQLExecute 함수
단일 행 또는 데이터 블록을 정방향으로 가져오기	SQLFetch 함수
문에서 커서 닫기	SQLFreeStmt 함수
결과 집합 열 수 반환	SQLNumResultCols 함수
커서 위치 지정, 행 집합의 데이터 새로 고침 또는 결과 집합의 데이터 업데이트 또는 삭제	SQLSetPos 함수
문 특성 설정	SQLSetStmtAttr 함수

참고 항목

ODBC API 참조
ODBC 헤더 파일