SQLFetch
SQLFetch#
결과 집합의 다음 행으로 커서를 진행시키고 바인드된 열을 가져온다.
SQLFetch()를 사용하여 사용자가 SQLBindCol()에 명시된 변수들에 데이터를 직접
받거나 SQLGetData()를 호출하여 페치 후에 열을 개별적으로 수신할 수 있다. 열이
바인드될 때 변환이 지정된 경우 SQLFetch()가 호출될 때 데이터 변환도 발생 한다.
구 문#
SQLRETURN SQLFetch (
SQLHSTMT stmt);
인 자#
| 자료유형 | 인자 | 사용 | 설명 |
|---|---|---|---|
| SQLHSTMT | stmt | 입력 | 명령문 핸들 |
결괏값#
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
SQL_NO_DATA
설 명#
stmt에서 가장 최근에 실행된 명령문이 SELECT 문인 경우에만 호출될 수 있다.
SQLBindCol()과 바인드된 애플리케이션 변수 개수는 결과 집합의 열 수를 초과해서는 안된다. 그렇지 않으면 SQLFetch()가 실패한다.
커서의 위치#
결과 집합이 생성될 때, 커서는 결과 집합의 시작 전에 위치한다. SQLFetch()는 결과 집합에서 바로 다음 행집합(rowset)을 반환한다. 예를 들어, 결과 집합이 전체 100개의 행들을 가지고 있을 때, 행집합의 크기가 5이면, 최초 SQLFetch()의 결과 행집합은 1 부터 5이다. 또한, 현재 행집합 52행부터 56행에 대한 결과 집합이라면, 그 다음 SQLFetch()에 의해 반환되는 새로운 행집합은 57행부터 61행, 반환 코드는 SQL_SUCCESS, 그리고 인출된 행들의 개수는 5개가 될것이다. 다음 테이블은 행집합을 보여주고 SQLFetch()에서 반환된 코드를 반환한다.
| 현재 행집합 | 반환 코드 | 새로운 행집합 | 페치된 행의 수 |
|---|---|---|---|
| 시작 전 | SQL_SUCCESS | 1 to 5 | 5 |
| 1 to 5 | SQL_SUCCESS | 6 to 10 | 5 |
| 52 to 56 | SQL_SUCCESS | 57 to 61 | 5 |
| 91 to 95 | SQL_SUCCESS | 96 to 100 | 5 |
| 93 to 97 | SQL_SUCCESS | 98 to 100. 행 4와 5에는 SQL_ROW_NOROW이 설정됨 | 3 |
| 96 to 100 | SQL_NO_DATA | 없음 | 0 |
| 99 to 100 | SQL_NO_DATA | 없음 | 0 |
| After end | SQL_NO_DATA | 없음 | 0 |
SQLFetch()는 반환 후에, 현재 행은 행집합의 첫 번째 행이다.
바인드된 열에 데이터 반환#
SQLFecth()는 각 행을 반환하면서 각 바인드된 열에 데이터를 위치시킨다. SQLBindCol()이 호출되었지만 바인드된 열이 없으면, SQLFetch()는 애플리케이션에 자료를 리턴하지는 않지만 커서를 진행시킨다. 이 경우 SQLFetch()가 다음 행으로 커서를 진행시키면 바인드되지 않은 열의 자료가 삭제 된다.
각 바인드된 열에 대해 SQLFetch()는 다음을 한다.
-
데이터가 NULL이면 길이/지시자 버퍼에 SQL_NULL_DATA를 설정하고 다음 column으로 진행한다.
-
SQLBindCol()의 type 인자에 명시된 타입의 데이터를 변환한다.
-
만약 데이터가 가변 길이 데이터 형으로 변환됐다면, SQLFetch()는 데이터 길이가 (SQL_C_CHAR로 변환 될 경우 null-termination 문자 포함) 데이터 버퍼 길이를 초과했는지를 검사한다. 만약 문자 데이터의 길이가 데이터 버퍼의 길이를 초과하면, SQLFetch()는 null-termination 문자 길이를 뺀 데이터 버퍼 길이에 맞춰 데이터를 자른다. 그렇게해서 null 문자로 데이터를 마무리한다. 만약 이진 데이터 길이가 데이터 버퍼 길이를 초과하면 SQLFetch()는 데이터 버퍼에 맞춰 데이터를 자른다. 데이터 버퍼의 길이는 SQLBindCol()에 length에 명시된다.
-
데이터 버퍼에 변환된 데이터를 위치시킨다.
-
길이/지시자 버퍼에 데이터 길이를 위치시킨다. 만약 지시자 포인터와 길이 포인터 둘다 같은 버퍼로 설정됐다면 유효한 데이터에 대해서 버퍼에는 길이가 기록되고 NULL 데이터에 대해서는 SQL_NULL_DATA가 기록된다. 만약 바운드 된 길이/지시자 버퍼가 없다면 SQLFetch()는 길이를 반환하지 않는다.
CLOB 데이터가 한 번에 가져올 수 없을 만큼 긴 경우, 드라이버가 CLOB 데이터의 바이트 수를 명확히 알 수 없기 때문에, 지시자 버퍼에 SQL_NO_TOTAL이 반환되고 SQLSTATE 값으로 01004(Data truncated)이 반환되며, SQLFetch()는 SQL_SUCCESS_WITH_INFO를 반환한다.
바인드된 데이터 버퍼와 길이/지시자 버퍼의 내용들은 만약 SQLFetch()가 SQL_SUCCESS나 또는 SQL_SUCCESS_WITH_INFO를 반환하지 않으면 정의되지 않는다. 즉, SQLFetch()의 결과가 SQL_ERROR 일 경우 유효하지 않은 값이다.
행 상태 배열 (Row Status Array)#
행 상태 배열에는 행집합에서의 각 열의 상태가 반환된다. 이러한 배열의 주소는 SQL_ATTR_ROW_STATUS_PTR 명령문 속성으로서 명시된다. 애플리케이션은 이 배열을 할당하고 배열의 크기는 SQL_ATTR_ROW_ARRAY_SIZE 명령문 속성에 의해 명시된 원소들의 수이다. 배열의 값들은 SQLFetch()에 의해 설정된다. 만약 SQL_ATTR_ROW_STATUS_PTR 명령문 속성의 값이 널 포인터이면, SQLFetch()는 행 상태를 반환하지 않는다.
Rows Fetched Buffer#
Rows fetched buffer에는 페치된 행들의 수 (행들이 페치되는 동안 발생한 오류 때문에 어떤 데이터도 반환되지 않은 행들까지도 포함) 가 반환된다. 이 버퍼의 주소는 SQL_ATTR_ROWS_FETCHED_PTR 명령문 속성으로서 명시된다. 이 버퍼는 애플리케이션에 의해 할당되고 SQLFetch()에 의해 설정된다. 만일 SQL_ATTR_ROWS_FETCHED_PTR 명령문 속성이 널 포인터이면, SQLFetch()는 페치된 행들의 수를 반환하지 않는다.
만약 SQLFetch()가 SQL_NO_DATA가 반환될 때를 빼고 (이런 경우 row fetched buffer 값은 0으로 설정됨) SQL_SUCCESS나 또는 SQL_SUCCESS_WITH_INFO를 반환하지 않으면 rows fetched buffer의 내용들은 정의되지 않는다.
오류 처리#
오류나 경고등의 처리는 행들에게 개별적으로나 또는 모든 함수에 적용할 수 있다.
함수에 대한 오류 또는 경고들
만일 임의의 경고가 모든 함수에 적용된다면 SQLFetch()는 SQL_SUCCESS_WITH_INFO와 적절한 SQLSTATE를 반환한다. 함수에 적용되는 경고 상태 레코드들은 상태 레코드들이 행들에 개별적으로 적용되기 전에 반환된다.
진 단#
| SQLSTATE | 설명 | 부연설명 |
|---|---|---|
| 01004 | 자료가 잘림 | 반환될 값의 크기가 주어진 버퍼의 크기보다 큼 |
| 07006 | 제한된 데이터 타입 속성 위반 | 결과 집합 내의 열의 데이터 값은 SQLBindCol()의 cType에서 명시된 데이터 타입으로 변환될 수 없다. |
| 08S01 | 통신 회선 장애 (데이터 송수신 실패) | Altibase CLI 드라이버와 DB간에 함수 처리가 완료되기 전에 통신 회선 실패 |
| HY000 | 일반 오류 |
관련 함수#
SQLBindCol
SQLDescribeCol
SQLExecDirect
SQLExecute
SQLFreeStmt
SQLGetData
SQLNumResultCols
SQLPrepare
예 제#
< $ALTIBASE_HOME/sample/SQLCLI/demo_ex2.cpp >
SQLBindCol() 예제 참조