SQLFetch 함수
규칙
버전 소개: ODBC 1.0 표준 준수: ISO 92
요약
SQLFetch 는 결과 집합에서 데이터의 다음 행 집합을 가져오고 모든 바인딩된 열에 대한 데이터를 반환합니다.
구문
SQLRETURN SQLFetch(
SQLHSTMT StatementHandle);
인수
StatementHandle
[입력] 문 핸들입니다.
반품
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR 또는 SQL_INVALID_HANDLE.
진단
SQLFetch가 SQL_ERROR 또는 SQL_SUCCESS_WITH_INFO 반환하는 경우 SQL_HANDLE_STMT HandleType 및 Handle of StatementHandle을 사용하여 SQLGetDiagRec 함수 를 호출하여 연결된 SQLSTATE 값을 가져올 수 있습니다. 다음 표에서는 일반적으로 SQLFetch에서 반환되는 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가 반환되는 경우 무시될 수 있습니다.) |
| 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에 대해 비동기 처리를 사용하도록 설정했습니다. SQLFetch 함수가 호출되었고 실행을 완료하기 전에 StatementHandle에서 SQLCancel 또는 SQLCancelHandle이 호출되었습니다. 그런 다음 StatementHandle에서 SQLFetch 함수가 다시 호출되었습니다. 또는 SQLFetch 함수가 호출되었고 실행을 완료하기 전에 다중 스레드 애플리케이션의 다른 스레드에서 StatementHandle에서 SQLCancel 또는 SQLCancelHandle이 호출되었습니다. |
| HY010 | 함수 시퀀스 오류 | (DM) StatementHandle과 연결된 연결 핸들에 대해 비동기적으로 실행되는 함수가 호출되었습니다. 이 비동기 함수는 SQLFetch 함수가 호출되었을 때 계속 실행되었습니다. (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.) |
| HY107 | 행 값이 범위를 벗어났습니다. | SQL_ATTR_CURSOR_TYPE 문 특성으로 지정된 값은 SQL_CURSOR_KEYSET_DRIVEN SQL_ATTR_KEYSET_SIZE 문 특성으로 지정된 값이 0보다 크고 SQL_ATTR_ROW_ARRAY_SIZE 문 특성으로 지정된 값보다 작습니다. |
| 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 를 호출해야 합니다. |
설명
SQLFetch 는 결과 집합의 다음 행 집합을 반환합니다. 결과 집합이 존재하는 경우에만 호출할 수 있습니다. 즉, 결과 집합을 만드는 호출 후 및 해당 결과 집합에 대한 커서가 닫혀 있기 전에 호출할 수 있습니다. 열이 바인딩된 경우 해당 열의 데이터를 반환합니다. 애플리케이션이 가져온 행 수를 반환할 행 상태 배열 또는 버퍼에 대한 포인터를 지정한 경우 SQLFetch 도 이 정보를 반환합니다. SQLFetch에 대한 호출은 SQLFetchScroll 호출과 혼합될 수 있지만 SQLExtendedFetch 호출과 혼합할 수는 없습니다. 자세한 내용은 데이터 행 가져오기를 참조 하세요.
ODBC 3*.x* 애플리케이션이 ODBC 2*.x* 드라이버에서 작동하는 경우 드라이버 관리자는 SQLExtendedFetch를 지원하는 ODBC 2*.x* 드라이버에 대해 SQLFetch 호출을 SQLExtendedFetch에 매핑합니다. ODBC 2*.x* 드라이버가 SQLExtendedFetch를 지원하지 않는 경우 드라이버 관리자는 단일 행만 가져올 수 있는 ODBC 2*.x* 드라이버의 SQLFetch 호출을 SQLFetch에 매핑합니다.
자세한 내용은 부록 G: 이전 버전과의 호환성을 위한 드라이버 지침의 블록 커서, 스크롤 가능한 커서 및 이전 버전과의 호환성을 참조하세요.
커서 위치 지정
결과 집합을 만들면 결과 집합이 시작되기 전에 커서가 배치됩니다. SQLFetch 는 다음 행 집합을 가져옵니다. FetchOrientation을 SQL_FETCH_NEXT 설정하여 SQLFetchScroll 을 호출하는 것과 같습니다. 커서에 대한 자세한 내용은 커서 및 블록 커서를 참조하세요.
SQL_ATTR_ROW_ARRAY_SIZE 문 특성은 행 집합의 행 수를 지정합니다. SQLFetch에서 가져오는 행 집합이 결과 집합의 끝 부분과 겹치면 SQLFetch는 부분 행 집합을 반환합니다. 즉, S + R - 1이 L보다 크면 S가 페치되는 행 집합의 시작 행이고 R은 행 집합 크기이고 L은 결과 집합의 마지막 행인 경우 행 집합의 첫 번째 L - S + 1 행만 유효합니다. 나머지 행은 비어 있으며 상태가 SQL_ROW_NOROW.
SQLFetch가 반환된 후 현재 행은 행 집합의 첫 번째 행입니다.
다음 표에 나열된 규칙은 이 섹션의 두 번째 테이블에 나열된 조건에 따라 SQLFetch를 호출한 후 커서 위치를 지정하는 방법을 설명합니다.
| 조건 | 새 행 집합의 첫 번째 행 |
|---|---|
| 시작하기 전 | 1 |
| CurrRowsetStart<= LastResultRow - RowsetSize[1] | CurrRowsetStart + RowsetSize[2] |
| CurrRowsetStart>LastResultRow - RowsetSize[1] | 종료 후 |
| 종료 후 | 종료 후 |
[1] 페치 간에 행 집합 크기가 변경되면 이전 페치와 함께 사용된 행 집합 크기입니다.
[2] 페치 간에 행 집합 크기가 변경되면 새 인출에 사용된 행 집합 크기입니다.
| 표기법 | 의미 |
|---|---|
| 시작하기 전 | 블록 커서는 결과 집합이 시작되기 전에 배치됩니다. 새 행 집합의 첫 번째 행이 결과 집합의 시작 전인 경우 SQLFetch는 SQL_NO_DATA 반환합니다. |
| 종료 후 | 블록 커서는 결과 집합의 끝 뒤에 배치됩니다. 새 행 집합의 첫 번째 행이 결과 집합의 끝 이후이면 SQLFetch는 SQL_NO_DATA 반환합니다. |
| CurrRowsetStart | 현재 행 집합의 첫 번째 행 수입니다. |
| LastResultRow | 결과 집합의 마지막 행 수입니다. |
| RowsetSize | 행 집합 크기입니다. |
예를 들어 결과 집합에 100개의 행이 있고 행 집합 크기가 5라고 가정합니다. 다음 표에서는 여러 시작 위치에 대해 SQLFetch에서 반환하는 행 집합 및 반환 코드를 보여 줍니다.
| 현재 행 집합 | 반환 코드 | 새 행 집합 | 가져온 행 수 |
|---|---|---|---|
| 시작하기 전 | SQL_SUCCESS | 1~5명 | 5 |
| 1~5명 | SQL_SUCCESS | 6~10 | 5 |
| 52-56 | SQL_SUCCESS | 57~61 | 5 |
| 91~95 | SQL_SUCCESS | 96~100 | 5 |
| 93~97 | SQL_SUCCESS | 98에서 100까지. 행 상태 배열의 행 4 및 5는 SQL_ROW_NOROW 설정됩니다. | 3 |
| 96~100 | SQL_NO_DATA | 없음 | 0 |
| 99~100 | SQL_NO_DATA | 없음 | 0 |
| 종료 후 | SQL_NO_DATA | 없음 | 0 |
바인딩된 열에서 데이터 반환
SQLFetch는 각 행을 반환할 때 해당 열에 바인딩된 버퍼의 각 바인딩된 열에 대한 데이터를 배치합니다. 바인딩 된 열이 없으면 SQLFetch 는 데이터를 반환하지 않지만 블록 커서를 앞으로 이동합니다. SQLGetData를 사용하여 데이터를 계속 검색할 수 있습니다. 커서가 다중 행 커서인 경우(즉, SQL_ATTR_ROW_ARRAY_SIZE 1보다 크면) SQL_GETDATA_EXTENSIONS InfoType을 사용하여 SQLGetInfo를 호출할 때 SQL_GD_BLOCK 반환되는 경우에만 SQLGetData를 호출할 수 있습니다. (자세한 내용은 를 참조하세요 .SQLGetData.)
행 의 각 바인딩된 열에 대해 SQLFetch 는 다음을 수행합니다.
길이/표시기 버퍼를 SQL_NULL_DATA 설정하고 데이터가 NULL인 경우 다음 열로 진행합니다. 데이터가 NULL이고 길이/표시기 버퍼가 바인딩 되지 않은 경우 SQLFetch 는 행에 대해 SQLSTATE 22002(표시기 변수가 필요하지만 제공되지 않음)를 반환하고 다음 행으로 진행합니다. 길이/표시기 버퍼의 주소를 확인하는 방법에 대한 자세한 내용은 SQLBindCol의 "버퍼 주소"를 참조하세요.
열의 데이터가 NULL 이 아니면 SQLFetch 가 2단계로 진행됩니다.
SQL_ATTR_MAX_LENGTH 문 특성이 0이 아닌 값으로 설정되고 열에 문자 또는 이진 데이터가 포함된 경우 데이터는 SQL_ATTR_MAX_LENGTH 바이트로 잘립니다.
참고 항목
SQL_ATTR_MAX_LENGTH 문 특성은 네트워크 트래픽을 줄이기 위한 것입니다. 일반적으로 데이터를 네트워크를 통해 반환하기 전에 잘리는 데이터 원본에 의해 구현됩니다. 드라이버 및 데이터 원본은 이를 지원할 필요가 없습니다. 따라서 데이터가 특정 크기로 잘리도록 하려면 애플리케이션에서 해당 크기의 버퍼를 할당하고 SQLBindCol의 cbValueMax 인수에서 크기를 지정해야 합니다.
데이터를 SQLBindCol의 TargetType에 지정된 형식으로 변환합니다.
데이터가 문자 또는 이진 과 같은 가변 길이 데이터 형식으로 변환된 경우 SQLFetch 는 데이터 길이가 데이터 버퍼의 길이를 초과하는지 여부를 확인합니다. 문자 데이터 길이(null 종료 문자 포함)가 데이터 버퍼의 길이를 초과하면 SQLFetch는 데이터를 데이터 버퍼의 길이로 잘라 null 종료 문자의 길이를 줄입니다. 그런 다음, 데이터를 null로 종료합니다. 이진 데이터의 길이가 데이터 버퍼의 길이를 초과하면 SQLFetch는 데이터 버퍼의 길이로 자른다. 데이터 버퍼의 길이는 SQLBindCol에서 BufferLength로 지정됩니다.
SQLFetch 는 고정 길이 데이터 형식으로 변환된 데이터를 잘라내지 않습니다. 항상 데이터 버퍼의 길이가 데이터 형식의 크기라고 가정합니다.
변환된(및 잘렸을 수 있음) 데이터를 데이터 버퍼에 넣습니다. 데이터 버퍼의 주소를 확인하는 방법에 대한 자세한 내용은 SQLBindCol의 "버퍼 주소"를 참조하세요.
데이터의 길이를 길이/표시기 버퍼에 넣습니다. 표시기 포인터와 길이 포인터가 모두 동일한 버퍼로 설정된 경우(SQLBindCol 호출과 마찬가지로) 길이는 유효한 데이터에 대한 버퍼에 기록되고 SQL_NULL_DATA NULL 데이터의 버퍼에 기록됩니다. 길이/표시기 버퍼가 바인딩 되지 않은 경우 SQLFetch 는 길이를 반환하지 않습니다.
문자 또는 이진 데이터의 경우 데이터 버퍼가 너무 작아서 변환 후 및 잘림 전의 데이터 길이입니다. 드라이버가 변환 후 데이터의 길이를 확인할 수 없는 경우 긴 데이터가 있는 경우와 마찬가지로 길이를 SQL_NO_TOTAL 설정합니다. SQL_ATTR_MAX_LENGTH 문 특성으로 인해 데이터가 잘린 경우 이 특성의 값은 실제 길이 대신 길이/표시기 버퍼에 배치됩니다. 이 특성은 변환 전에 서버의 데이터를 자르도록 설계되었으므로 드라이버가 실제 길이를 파악할 방법이 없기 때문입니다.
다른 모든 데이터 형식의 경우 변환 후의 데이터 길이입니다. 즉, 데이터가 변환된 형식의 크기입니다.
길이/표시기 버퍼의 주소를 확인하는 방법에 대한 자세한 내용은 SQLBindCol의 "버퍼 주소"를 참조하세요.
데이터를 변환하는 동안 상당한 숫자가 손실되지 않고 잘리는 경우(예: 변환할 때 실수 1.234가 정수 1로 잘림) SQLFetch 는 SQLSTATE 01S07(소수점 잘림)을 반환하고 SQL_SUCCESS_WITH_INFO. 데이터 버퍼의 길이가 너무 작기 때문에 데이터가 잘리는 경우(예: "abcdef" 문자열이 4 바이트 버퍼에 배치됨) SQLFetch 는 SQLSTATE 01004(잘린 데이터)를 반환하고 SQL_SUCCESS_WITH_INFO. SQL_ATTR_MAX_LENGTH 문 특성 으로 인해 데이터가 잘리는 경우 SQLFetch 는 SQL_SUCCESS 반환하고 SQLSTATE 01S07(소수점 잘림) 또는 SQLSTATE 01004(잘린 데이터)를 반환하지 않습니다. 변환 중에 데이터가 유효 자릿수 손실로 잘리는 경우(예: 100,000보다 큰 SQL_INTEGER 값이 SQL_C_TINYINT 변환된 경우) SQLFetch 는 SQLSTATE 22003(범위를 벗어난 숫자 값) 및 SQL_ERROR(행 집합 크기가 1인 경우) 또는 SQL_SUCCESS_WITH_INFO(행 집합 크기가 1보다 큰 경우)를 반환합니다.
SQLFetch 또는 SQLFetchScroll이 SQL_SUCCESS 또는 SQL_SUCCESS_WITH_INFO 반환하지 않으면 바인딩된 데이터 버퍼의 내용과 길이/표시기 버퍼가 정의되지 않습니다.
행 상태 배열
행 상태 배열은 행 집합에 있는 각 행의 상태를 반환하는 데 사용됩니다. 이 배열의 주소는 SQL_ATTR_ROW_STATUS_PTR 문 특성으로 지정됩니다. 배열은 애플리케이션에 의해 할당되며 SQL_ATTR_ROW_ARRAY_SIZE 문 특성에 지정된 만큼의 요소가 있어야 합니다. 해당 값은 SQLFetch, SQLFetchScroll 및 SQLBulkOperations 또는 SQLSetPos에 의해 설정됩니다(커서가 SQLExtendedFetch에 의해 배치된 후 호출된 경우 제외). SQL_ATTR_ROW_STATUS_PTR 문 특성의 값이 null 포인터인 경우 이러한 함수는 행 상태를 반환하지 않습니다.
SQLFetch 또는 SQLFetchScroll이 SQL_SUCCESS 또는 SQL_SUCCESS_WITH_INFO 반환하지 않으면 행 상태 배열 버퍼의 내용이 정의되지 않습니다.
행 상태 배열에 다음 값이 반환됩니다.
| 행 상태 배열 값 | 설명 |
|---|---|
| SQL_ROW_SUCCESS | 행이 성공적으로 페치되었으며 이 결과 집합에서 마지막으로 가져온 이후 변경되지 않았습니다. |
| SQL_ROW_SUCCESS_WITH_INFO | 행이 성공적으로 페치되었으며 이 결과 집합에서 마지막으로 가져온 이후 변경되지 않았습니다. 그러나 행에 대한 경고가 반환되었습니다. |
| SQL_ROW_ERROR | 행을 가져오는 동안 오류가 발생했습니다. |
| SQL_ROW_UPDATED[1], [2] 및 [3] | 행이 성공적으로 페치되었으며 이 결과 집합에서 마지막으로 가져온 이후 변경되었습니다. 이 결과 집합에서 행을 다시 가져오거나 SQLSetPos에 의해 새로 고쳐지면 상태가 행의 새 상태로 변경됩니다. |
| SQL_ROW_DELETED[3] | 이 결과 집합에서 마지막으로 가져온 이후 행이 삭제되었습니다. |
| SQL_ROW_ADDED[4] | 행이 SQLBulkOperations에 의해 삽입되었습니다. 이 결과 집합에서 행을 다시 가져오거나 SQLSetPos에 의해 새로 고쳐지면 해당 상태가 SQL_ROW_SUCCESS. |
| SQL_ROW_NOROW | 행 집합이 결과 집합의 끝 부분과 겹치며 행 상태 배열의 이 요소에 해당하는 행이 반환되지 않았습니다. |
[1] 키 집합, 혼합 및 동적 커서의 경우 키 값이 업데이트되면 데이터 행이 삭제된 것으로 간주되고 새 행이 추가됩니다.
[2] 일부 드라이버는 데이터에 대한 업데이트를 검색할 수 없으므로 이 값을 반환할 수 없습니다. 드라이버가 리페치된 행에 대한 업데이트를 검색할 수 있는지 여부를 확인하기 위해 애플리케이션은 SQL_ROW_UPDATES 옵션을 사용하여 SQLGetInfo를 호출합니다.
[3] SQLFetch는 SQLFetchScroll에 대한 호출과 혼합된 경우에만 이 값을 반환할 수 있습니다. SQLFetch가 결과 집합을 통해 앞으로 이동하고 단독으로 사용될 때 행을 다시 페치하지 않기 때문입니다. 다시 페치된 행이 없으므로 SQLFetch 는 이전에 가져온 행에 대한 변경 내용을 검색하지 않습니다. 그러나 SQLFetchScroll이 이전에 가져온 행 앞에 커서를 배치하고 SQLFetch를 사용하여 해당 행을 가져오는 경우 SQLFetch는 해당 행에 대한 변경 내용을 검색할 수 있습니다.
[4] SQLBulkOperations에서만 반환됩니다. SQLFetch 또는 SQLFetchScroll에서 설정하지 않습니다.
가져온 행 버퍼
인출된 행 버퍼는 페치되는 동안 오류가 발생하여 데이터가 반환되지 않은 행을 포함하여 페치된 행 수를 반환하는 데 사용됩니다. 즉, 행 상태 배열의 값이 SQL_ROW_NOROW 않은 행의 수입니다. 이 버퍼의 주소는 SQL_ATTR_ROWS_FETCHED_PTR 문 특성으로 지정됩니다. 버퍼는 애플리케이션에 의해 할당됩니다. SQLFetch 및 SQLFetchScroll에 의해 설정됩니다. SQL_ATTR_ROWS_FETCHED_PTR 문 특성의 값이 null 포인터인 경우 이러한 함수는 가져온 행 수를 반환하지 않습니다. 결과 집합의 현재 행 수를 확인하기 위해 애플리케이션은 SQL_ATTR_ROW_NUMBER 특성을 사용하여 SQLGetStmtAttr을 호출할 수 있습니다.
sqlFetch 또는 SQLFetchScroll이 SQL_NO_DATA 반환되는 경우 를 제외하고 SQLFetch 또는 SQLFetchScroll 이 SQL_SUCCESS 또는 SQL_SUCCESS_WITH_INFO 반환하지 않으면 페치된 행 버퍼의 내용이 정의되지 않습니다. 이 경우 페치된 행의 값은 0으로 설정됩니다.
오류 처리
오류 및 경고는 개별 행 또는 전체 함수에 적용할 수 있습니다. 진단 레코드에 대한 자세한 내용은 진단 및 SQLGetDiagField를 참조하세요.
전체 함수에 대한 오류 및 경고
SQLSTATE HYT00(시간 제한 만료) 또는 SQLSTATE 24000(잘못된 커서 상태 )과 같은 전체 함수에 오류가 적용되는 경우 SQLFetch 는 SQL_ERROR 및 해당 SQLSTATE를 반환합니다. 행 집합 버퍼의 내용은 정의되지 않으며 커서 위치는 변경되지 않습니다.
경고가 전체 함수에 적용되는 경우 SQLFetch는 SQL_SUCCESS_WITH_INFO 및 적용 가능한 SQLSTATE를 반환합니다. 전체 함수에 적용되는 경고에 대한 상태 레코드는 개별 행에 적용되는 상태 레코드 전에 반환됩니다.
개별 행의 오류 및 경고
오류(예: SQLSTATE 22012(0으로 나누기)) 또는 경고(예: SQLSTATE 01004(잘린 데이터))가 단일 행 에 적용되는 경우 SQLFetch는 다음을 수행합니다.
행 상태 배열의 해당 요소를 오류에 대해 SQL_ROW_ERROR 설정하거나 경고에 대한 SQL_ROW_SUCCESS_WITH_INFO 설정합니다.
오류 또는 경고에 대한 SQLSTATE를 포함하는 0개 이상의 상태 레코드를 추가합니다.
상태 레코드의 행 및 열 번호 필드를 설정합니다. SQLFetch에서 행 또는 열 번호를 확인할 수 없는 경우 해당 숫자를 각각 SQL_ROW_NUMBER_UNKNOWN 또는 SQL_COLUMN_NUMBER_UNKNOWN 설정합니다. 상태 레코드가 특정 열 에 적용되지 않으면 SQLFetch 는 열 번호를 SQL_NO_COLUMN_NUMBER 설정합니다.
SQLFetch는 행 집합의 모든 행을 페치할 때까지 행을 계속 페치 합니다. 행 집합의 모든 행에서 오류가 발생하지 않는 한(상태 SQL_ROW_NOROW 있는 행 포함 안 됨) SQL_SUCCESS_WITH_INFO 반환하며, 이 경우 SQL_ERROR 반환합니다. 특히 행 집합 크기가 1이고 해당 행 에서 오류가 발생하면 SQLFetch 는 SQL_ERROR 반환합니다.
SQLFetch 는 상태 레코드를 행 번호 순서로 반환합니다. 즉, 알 수 없는 행에 대한 모든 상태 레코드를 반환합니다(있는 경우). 그런 다음 첫 번째 행에 대한 모든 상태 레코드(있는 경우)를 반환한 다음 두 번째 행(있는 경우)에 대한 모든 상태 레코드를 반환합니다. 각 행의 상태 레코드는 상태 레코드를 정렬하기 위한 일반 규칙에 따라 정렬됩니다. 자세한 내용은 SQLGetDiagField의 "상태 레코드 시퀀스" 를 참조하세요.
설명자 및 SQLFetch
다음 섹션에서는 SQLFetch가 설명자와 상호 작용하는 방법을 설명합니다.
인수 매핑
드라이버는 SQLFetch의 인수에 따라 설명자 필드를 설정하지 않습니다.
기타 설명자 필드
다음 설명자 필드는 SQLFetch에서 사용됩니다.
| 설명자 필드 | Desc. | 필드 | 다음을 통해 설정 |
|---|---|---|---|
| SQL_DESC_ARRAY_SIZE | ARD | 헤더 | SQL_ATTR_ROW_ARRAY_SIZE 문 특성 |
| SQL_DESC_ARRAY_STATUS_PTR | IRD | 헤더 | SQL_ATTR_ROW_STATUS_PTR 문 특성 |
| SQL_DESC_BIND_OFFSET_PTR | ARD | 헤더 | SQL_ATTR_ROW_BIND_OFFSET_PTR 문 특성 |
| SQL_DESC_BIND_TYPE | ARD | 헤더 | SQL_ATTR_ROW_BIND_TYPE 문 특성 |
| SQL_DESC_COUNT | ARD | 헤더 | SQLBindCol의 ColumnNumber 인수 |
| SQL_DESC_DATA_PTR | ARD | 레코드 | SQLBindCol의 TargetValuePtr 인수 |
| SQL_DESC_INDICATOR_PTR | ARD | 레코드 | SQLBindCol의 StrLen_or_IndPtr 인수 |
| SQL_DESC_OCTET_LENGTH | ARD | 레코드 | SQLBindCol의 BufferLength 인수 |
| SQL_DESC_OCTET_LENGTH_PTR | ARD | 레코드 | SQLBindCol의 StrLen_or_IndPtr 인수 |
| SQL_DESC_ROWS_PROCESSED_PTR | IRD | 헤더 | SQL_ATTR_ROWS_FETCHED_PTR 문 특성 |
| SQL_DESC_TYPE | ARD | 레코드 | SQLBindCol의 TargetType 인수 |
모든 설명자 필드는 SQLSetDescField를 통해 설정할 수도 있습니다.
별도의 길이 및 표시기 버퍼
애플리케이션은 길이 및 표시기 값을 보유하는 데 사용할 수 있는 단일 버퍼 또는 두 개의 별도 버퍼를 바인딩할 수 있습니다. 애플리케이션이 SQLBindCol을 호출할 때 드라이버는 ARD의 SQL_DESC_OCTET_LENGTH_PTR 및 SQL_DESC_INDICATOR_PTR 필드를 동일한 주소로 설정하며, 이 필드는 StrLen_or_IndPtr 인수에 전달됩니다. 애플리케이션이 SQLSetDescField 또는 SQLSetDescRec를 호출하는 경우 이러한 두 필드를 서로 다른 주소로 설정할 수 있습니다.
SQLFetch 는 애플리케이션이 별도의 길이 및 표시기 버퍼를 지정했는지 여부를 결정합니다. 이 경우 데이터가 NULL 이 아닌 경우 SQLFetch 는 표시기 버퍼를 0으로 설정하고 길이 버퍼의 길이를 반환합니다. 데이터가 NULL 이면 SQLFetch 는 표시기 버퍼를 SQL_NULL_DATA 설정하고 길이 버퍼를 수정하지 않습니다.
코드 예
SQLBindCol, SQLColumns, SQLGetData 및 SQLProcedures를 참조하세요.
관련 함수
| 추가 정보 | 참조 |
|---|---|
| 결과 집합의 열에 버퍼 바인딩 | SQLBindCol 함수 |
| 문 처리 취소 | SQLCancel 함수 |
| 결과 집합의 열에 대한 정보 반환 | SQLDescribeCol 함수 |
| SQL 문 실행 | SQLExecDirect 함수 |
| 준비된 SQL 문 실행 | SQLExecute 함수 |
| 데이터 블록을 가져오거나 결과 집합을 스크롤합니다. | SQLFetchScroll 함수 |
| 문에서 커서 닫기 | SQLFreeStmt 함수 |
| 데이터 열의 일부 또는 전체 가져오기 | SQLGetData 함수 |
| 결과 집합 열 수 반환 | SQLNumResultCols 함수 |
| 실행을 위한 문 준비 | SQLPrepare 함수 |