SQLGetData
SQLGetData#
결과 집합에서 단일 열에 대한 데이터를 검색한다.
각 열에 대해 SQLGetData()를 호출한 후에는 다음 행을 검색하기 위해 SQLFetch()가 호출된다.
구 문#
SQLRETURN SQLGetData (
SQLHSTMT stmt,
SQLSMALLINT col,
SQLSMALLINT cType,
SQLPOINTER Value,
SQLLEN ValueMax,
SQLLEN * pcbValue );
인 자#
| 자료유형 | 인자 | 사용 | 설명 |
|---|---|---|---|
| SQLHSTMT | stmt | 입력 | 명령문 핸들 |
| SQLSMALLINT | col | 입력 | column의 순서. 1부터 시작 |
| SQLSMALLINT | cType | 입력 | *Value 버퍼의 C 데이터 타입의 타입 식별자 |
| SQLPOINTER | Value | 출력 | 데이터를 반환 할 버퍼의 포인터 |
| SQLLEN | ValueMax | 입력 | - *Value 버퍼의 길이 (byte 단위) - * Value에 character data를 반환할 때 *Value는 null-termination character를 위한 공간을 포함해야만 한다. 그렇지 않으면, Altibase CLI 드라이버는 데이터를 자른다. 고정 길이 data (integer 또는 date structure 등)를 반환할 경우는 Altibase CLI 드라이버가 ValueMax를 무시하기 때문에 충분한 버퍼 크기를 할당해야만 한다. 그렇지 않으면 Altibase CLI 드라이버는 버퍼의 끝을 지나 저장한다.(잘못된 메모리 연산 발생) - SQLGetData()는 ValueMax가 0 보다 작을 때 (0인 경우는 아님) SQLSTATE HY090을 (유효하지 않은 문자열 또는 버퍼 길이 길이) 반환한다. - Value가 null pointer로 설정 되 있다면 ValueMax는 Altibase CLI 드라이버에 의해 무시된다. |
| SQLLEN * | pcbValue | 출력 | - 길이 또는 지시자 변수를 반환할 버퍼의 포인터 - 이 변수가 null pointer 이면 어떤 길이나 지시자 값도 반환되지 않는다. 이 변수는 페치된 데이터가 NULL일 때 오류(SQL_SUCCESS_WITH_INFO)를 반환한다. - SQLGetData()는 길이/지시자 버퍼에 다음 값들을 반환한다: SQL_NULL_DATA |
결괏값#
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_NO_DATA
SQL_ERROR
SQL_INVALID_HANDLE
설 명#
SQLGetData()는 명시 된 열의 데이터를 반환한다. SQLGetData()는 SQLFetch()에 의해서 한 개 혹은 그 이상의 행들이 페치 된 후에만 호출 될 수 있다. 비록 몇 개의 제한 대상이 있지만 행의 몇몇 열들은 바인드하고 나머지에 대해서는 SQLGetData()를 호출하는게 가능하다.
SQLGetData() 사용#
이 함수는 바인드 되지 않은 열들의 (마지막 바인드된 열의 값 보다 1이 더 큰) 데이터만을 반환한다. SQLGetData()의 각 호출에 있어서 col의 값은 이전 호출의 col의 값 보다 크거나 같아야만 한다; 즉, 데이터는 열 번호가 증가하는 순으로 검색되야만 한다.
SQLGetData()로 데이터 검색하기#
명시된 열에 대한 데이터를 반환하기 위해 SQLGetData()는 다음 일련의 연속된 단계를 수행한다.
-
만약 그 열에 대한 모든 데이터를 이미 반환했다면 SQL_NO_DATA를 반환한다.
-
만약 데이터가 NULL이면 *pcbValue에 SQL_NULL_DATA를 설정한다. 만약 그 열에 대한 데이터가 NULL이 아니면, SQLGetData()는 다음 단계로 진행한다.
-
만약 데이터가 문자형이나 이진형과 같은 가변 길이 데이터 타입으로 변환됐다면, SQLGetData()는 데이터 길이가 ValueMax를 초과했는가를 검사한다. 만약 null-termination 문자를 포함해 문자 데이터의 길이가 ValueMax를 초과했다면, SQLGetData()는 null-termination 문자 길이를 뺀 ValueMax 길이에 맞춰 데이터를 자른다. 그렇게해서 null 문자로 데이터를 마무리한다. 만약 이진 데이터 길이가 데이터 버퍼 길이를 초과하면 SQLGetData()는 ValueMax에 맞춰 데이터를 자른다.
만약 데이터 버퍼가 작아서 null-termination 문자를 포함할 수 없다면 SQLGetData()는 SQL_SUCCESS_WITH_INFO를 반환한다.
SQLGetData()는 고정 길이 데이터 타입으로 변환된 데이터를 결코 자르지 않는다; SQLGetData()는 항상 *Value의 길이는 데이터 타입의 크기다라고 가정한다. -
변환된 (아마도 잘린) 데이터를 *Value에 놓는다.
-
데이터 길이를 *pcbValue에 놓는다. 만약 *pcbValue가 null pointer이면, SQLGetData()는 길이를 반환하지 않는다.
CLOB 데이터가 한 번에 가져올 수 없을 만큼 긴 경우, 드라이버가 CLOB 데이터의 바이트 수를 명확히 알 수 없기 때문에, *pcbValue에 SQL_NO_TOTAL이 반환되고 SQLSTATE 값으로 01004(Data truncated)이 반환되며, SQLGetData()는 SQL_SUCCESS_WITH_INFO를 반환한다.
길이/지시자 버퍼에 반환되는 값은 SQLGetData()를 매번 호출할 때마다 이전 호출에서 반환된 바이트 수만큼 감소한다. -
만약 데이터가 변환 중에 중대한 손실은 없이 잘리거나 (e.g. 실수 1.234는 정수 1로 변환될 때 잘린다.) 또는 ValueMax가 너무 작다면 (e.g. 문자열 "abcde"가 4-byte 버퍼에 놓인다.) SQLGetData()는 SQLSTATE 01004 (데이터 잘림)와 SQL_SUCCESS_WITH_INFO를 반환한다.
만약 SQLGetData()가 SQL_SUCCESS 또는 SQL_SUCCESS_WITH_INFO를 반환하지 않으면 바인드된 데이터 버퍼의 내용들과 길이/지시자 버퍼는 정의 되지 않는다.
진 단#
| SQLSTATE | 설명 | 부연설명 |
|---|---|---|
| 01004 | 자료가 잘림 | 반환 될 값의 크기가 주어진 버퍼의 크기보다 클 경우 |
| 07009 | 유효하지 않은 설명자 인덱스 | - col에 명시된 값이 0임 - col에 명시된 값이 결과 집합의 columns의 수 보다 큼 - 애플리케이션이 이미 현재 행에 대해 SLQGetData()를 호출함 - 현재 호출에서 명시된 열의 수가 이전 호출에서 명시된 열의 수 보다 적음 |
| HY000 | 일반 오류 | |
| HY010 | 함수 연속 오류 | - 주어진 stmt는 이 함수를 수행할 수 없음. - 결과 집합을 생성하는 단계를 거친 후에 이 함수 호출 가능 |
| HY090 | 유효하지 않은 문자열 또는 버퍼 길이 | valueMax가 0 보다 작음 |
관련 함수#
SQLBindCol
SQLExecDirect
SQLExecute
SQLFetch
예 제#
< $ALTIBASE_HOME/sample/SQLCLI/demo_info1.cpp >
SQLGetTypeInfo() 예제 참조