SQLGetData 함수
규칙
버전 소개: ODBC 1.0 표준 준수: ISO 92
요약
SQLGetData는 SQLParamData가 SQL_PARAM_DATA_AVAILABLE 반환한 후 결과 집합의 단일 열 또는 단일 매개 변수에 대한 데이터를 검색합니다. 여러 번 호출하여 부분의 가변 길이 데이터를 검색할 수 있습니다.
구문
SQLRETURN SQLGetData(
SQLHSTMT StatementHandle,
SQLUSMALLINT Col_or_Param_Num,
SQLSMALLINT TargetType,
SQLPOINTER TargetValuePtr,
SQLLEN BufferLength,
SQLLEN * StrLen_or_IndPtr);
인수
StatementHandle
[입력] 문 핸들입니다.
Col_or_Param_Num
[입력] 열 데이터를 검색하는 경우 데이터를 반환할 열의 수입니다. 결과 집합 열은 1부터 열 순서를 늘려 번호가 매겨집니다. 책갈피 열은 열 번호 0입니다. 책갈피를 사용하는 경우에만 지정할 수 있습니다.
매개 변수 데이터를 검색하는 경우 1에서 시작하는 매개 변수의 서수입니다.
TargetType
[입력] *TargetValuePtr 버퍼의 C 데이터 형식에 대한 형식 식별자입니다. 유효한 C 데이터 형식 및 형식 식별자 목록은 부록 D: 데이터 형식의 C 데이터 형식 섹션을 참조하세요.
TargetType이 SQL_ARD_TYPE 경우 드라이버는 ARD의 SQL_DESC_CONCISE_TYPE 필드에 지정된 형식 식별자를 사용합니다. TargetType이 SQL_APD_TYPE 경우 SQLGetData는 SQLBindParameter에 지정된 것과 동일한 C 데이터 형식을 사용합니다. 그렇지 않으면 SQLGetData에 지정된 C 데이터 형식이 SQLBindParameter에 지정된 C 데이터 형식을 재정의합니다. SQL_C_DEFAULT 경우 드라이버는 원본의 SQL 데이터 형식에 따라 기본 C 데이터 형식을 선택합니다.
확장된 C 데이터 형식을 지정할 수도 있습니다. 자세한 내용은 ODBC의 C 데이터 형식을 참조하세요.
TargetValuePtr
[출력] 데이터를 반환할 버퍼에 대한 포인터입니다.
TargetValuePtr은 NULL일 수 없습니다.
BufferLength
[입력] *TargetValuePtr 버퍼의 길이(바이트)입니다.
드라이버는 BufferLength를 사용하여 문자 또는 이진 데이터와 같은 가변 길이 데이터를 반환할 때 *TargetValuePtr 버퍼의 끝을 지나서 쓰는 것을 방지합니다. *TargetValuePtr에 문자 데이터를 반환할 때 드라이버는 null 종료 문자 수를 계산합니다. *따라서 TargetValuePtr 에는 null 종료 문자에 대한 공간이 포함되어야 합니다. 그렇지 않으면 드라이버가 데이터를 자른다.
드라이버가 정수 또는 날짜 구조와 같은 고정 길이 데이터를 반환하는 경우 드라이버는 BufferLength를 무시하고 버퍼가 데이터를 보유할 만큼 충분히 크다고 가정합니다. 따라서 애플리케이션이 고정 길이 데이터에 충분한 버퍼를 할당하거나 드라이버가 버퍼의 끝을 지나서 쓰는 것이 중요합니다.
BufferLength가 0보다 작지만 BufferLength가 0이 아닌 경우 SQLGetData는 SQLSTATE HY090(잘못된 문자열 또는 버퍼 길이)을 반환합니다.
StrLen_or_IndPtr
[출력] 길이 또는 표시기 값을 반환할 버퍼에 대한 포인터입니다. null 포인터인 경우 길이 또는 표시기 값이 반환되지 않습니다. 페치되는 데이터가 NULL이면 오류가 반환됩니다.
SQLGetData 는 길이/표시기 버퍼에서 다음 값을 반환할 수 있습니다.
반환할 수 있는 데이터의 길이
SQL_NO_TOTAL
SQL_NULL_DATA
자세한 내용은 이 항목의 길이/표시기 값 및 "메모" 사용을 참조하세요.
반품
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR 또는 SQL_INVALID_HANDLE.
진단
SQLGetData가 SQL_ERROR 또는 SQL_SUCCESS_WITH_INFO 반환하는 경우 SQL_HANDLE_STMT HandleType 및Handle of StatementHandle을 사용하여 SQLGetDiagRec 를 호출하여 관련 SQLSTATE 값을 가져올 수 있습니다. 다음 표에서는 SQLGetData에서 일반적으로 반환되는 SQLSTATE 값을 나열하고 이 함수의 컨텍스트에서 각 값을 설명합니다. "(DM)" 표기법은 드라이버 관리자가 반환한 SQLSTATE에 대한 설명 앞에 나와 있습니다. 달리 명시되지 않는 한 각 SQLSTATE 값과 연결된 반환 코드는 SQL_ERROR.
| SQLSTATE | Error | 설명 |
|---|---|---|
| 01000 | 일반 경고 | 드라이버 관련 정보 메시지입니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| 01004 | 문자열 데이터, 오른쪽 잘림 | Col_or_Param_Num 지정된 열에 대한 모든 데이터를 함수에 대한 단일 호출로 검색할 수 있는 것은 아닙니다. SQL_NO_TOTAL 또는 SQLGetData에 대한 현재 호출 전에 지정된 열에 남아 있는 데이터의 길이가 *StrLen_or_IndPtr 반환됩니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. 단일 열에 대해 SQLGetData를 여러 번 호출하는 방법에 대한 자세한 내용은 "주석"을 참조하세요. |
| 01S07 | 분수 잘림 | 하나 이상의 열에 대해 반환된 데이터가 잘렸습니다. 숫자 데이터 형식의 경우 숫자의 소수 부분이 잘렸습니다. 시간, 타임스탬프 및 시간 구성 요소가 포함된 간격 데이터 형식의 경우 시간의 소수 부분이 잘렸습니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| 07006 | 제한된 데이터 형식 특성 위반 | 결과 집합에 있는 열의 데이터 값은 TargetType 인수로 지정된 C 데이터 형식으로 변환할 수 없습니다. |
| 07009 | 설명자 인덱스가 잘못되었습니다. | 인수 Col_or_Param_Num 지정된 값이 0이고 SQL_ATTR_USE_BOOKMARKS 문 특성이 SQL_UB_OFF 설정되었습니다. 인수 Col_or_Param_Num 지정된 값이 결과 집합의 열 수보다 큽니다. Col_or_Param_Num 값이 사용 가능한 매개 변수의 서수와 같지 않습니다. (DM) 지정된 열이 바인딩되었습니다. 이 설명은 SQLGetInfo의 SQL_GETDATA_EXTENSIONS 옵션에 대한 SQL_GD_BOUND 비트 마스크를 반환하는 드라이버에는 적용되지 않습니다. (DM) 지정된 열의 수가 가장 높은 바운드 열 수보다 작거나 같습니다. 이 설명은 SQLGetInfo의 SQL_GETDATA_EXTENSIONS 옵션에 대한 SQL_GD_ANY_COLUMN 비트 마스크를 반환하는 드라이버에는 적용되지 않습니다. (DM) 애플리케이션이 이미 현재 행에 대해 SQLGetData를 호출했습니다. 현재 호출에 지정된 열 수가 이전 호출에 지정된 열 수보다 작으며 드라이버는 SQLGetInfo의 SQL_GETDATA_EXTENSIONS 옵션에 대한 SQL_GD_ANY_ORDER 비트 마스크를 반환하지 않습니다. (DM) TargetType 인수가 SQL_ARD_TYPE ARD의 Col_or_Param_Num 설명자 레코드가 일관성 검사에 실패했습니다. (DM) TargetType 인수가 SQL_ARD_TYPE ARD의 SQL_DESC_COUNT 필드 값이 Col_or_Param_Num 인수보다 작습니다. |
| 08S01 | 통신 링크 실패 | 드라이버와 드라이버가 연결된 데이터 원본 간의 통신 링크는 함수가 처리를 완료하기 전에 실패했습니다. |
| 22002 | 표시기 변수가 필요하지만 제공되지 않음 | StrLen_or_IndPtr null 포인터였고 NULL 데이터가 검색되었습니다. |
| 22003 | 숫자 값이 범위를 벗어났습니다. | 열의 숫자 값(숫자 또는 문자열)을 반환하면 숫자의 전체 부분(소수 부분이 아닌)이 잘렸을 것입니다. 자세한 내용은 부록 D: 데이터 형식을 참조 하세요. |
| 22007 | 날짜/시간 형식이 잘못되었습니다. | 결과 집합의 문자 열이 C 날짜, 시간 또는 타임스탬프 구조에 바인딩되었고 열의 값이 각각 잘못된 날짜, 시간 또는 타임스탬프였습니다. 자세한 내용은 부록 D: 데이터 형식을 참조 하세요. |
| 22012 | 0으로 나누기 | 산술 식에서 0으로 나누기된 값이 반환되었습니다. |
| 22015 | 간격 필드 오버플로 | 정확한 숫자 또는 간격 SQL 형식에서 간격 C 형식으로 할당하면 선행 필드에서 상당한 자릿수가 손실되었습니다. 데이터를 간격 C 형식으로 반환할 때 간격 C 형식의 SQL 형식 값에 대한 표현이 없었습니다. |
| 22018 | 캐스트 사양에 잘못된 문자 값 | 결과 집합의 문자 열이 문자 C 버퍼로 반환되었고 열에 버퍼의 문자 집합에 표현이 없는 문자가 포함되었습니다. C 형식은 정확히 또는 근사치 숫자, 날짜/시간 또는 간격 데이터 형식입니다. 열의 SQL 형식은 문자 데이터 형식입니다. 열의 값이 바인딩된 C 형식의 유효한 리터럴이 아니었습니다. |
| 24000 | 커서 상태가 잘못되었습니다. | (DM) 먼저 SQLFetch 또는 SQLFetchScroll을 호출하지 않고 함수를 호출하여 필요한 데이터 행에 커서를 배치했습니다. (DM) StatementHandle이 실행된 상태였지만 결과 집합이 StatementHandle과 연결되지 않았습니다. StatementHandle에서 커서가 열려 있고 SQLFetch 또는 SQLFetchScroll이 호출되었지만 결과 집합이 시작되기 전이나 결과 집합의 끝 뒤에 커서가 배치되었습니다. |
| HY000 | 일반 오류 | 특정 SQLSTATE가 없고 구현별 SQLSTATE가 정의되지 않은 오류가 발생했습니다. MessageText 버퍼에서 SQLGetDiagRec에서 반환된 오류 메시지는 오류와 그 원인을 설명합니다. |
| HY001 | 메모리 할당 오류 | 드라이버가 함수 실행 또는 완료를 지원하는 데 필요한 메모리를 할당할 수 없습니다. |
| HY003 | 프로그램 유형이 범위를 벗어났습니다. | (DM) TargetType 인수가 유효한 데이터 형식, SQL_C_DEFAULT, SQL_ARD_TYPE(열 데이터를 검색하는 경우) 또는 SQL_APD_TYPE(매개 변수 데이터를 검색하는 경우)가 아닙니다. (DM) Col_or_Param_Num 인수가 0이고 TargetType 인수가 고정 길이 책갈피 또는 가변 길이 책갈피의 SQL_C_VARBOOKMARK SQL_C_BOOKMARK 않았습니다. |
| HY008 | 작업이 취소됨 | StatementHandle에 대해 비동기 처리를 사용하도록 설정했습니다. 함수가 호출되었고 실행이 완료되기 전에 StatementHandle에서 SQLCancel 또는 SQLCancelHandle이 호출된 후 StatementHandle에서 함수가 다시 호출되었습니다. 함수가 호출되었고 실행을 완료하기 전에 다중 스레드 애플리케이션의 다른 스레드에서 StatementHandle에서 SQLCancel 또는 SQLCancelHandle을 호출한 다음 StatementHandle에서 함수를 다시 호출했습니다. |
| HY009 | null 포인터를 잘못 사용했습니다. | (DM) TargetValuePtr 인수가 null 포인터였습니다. |
| HY010 | 함수 시퀀스 오류 | (DM) 지정된 StatementHandle 이 실행된 상태가 아닙니다. 이 함수는 먼저 SQLExecDirect, SQLExecute 또는 카탈로그 함수를 호출하지 않고 호출되었습니다. (DM) StatementHandle과 연결된 연결 핸들에 대해 비동기적으로 실행되는 함수가 호출되었습니다. 이 비동기 함수는 SQLGetData 함수가 호출되었을 때 계속 실행되었습니다. (DM) 이 함수가 아닌 비동기 실행 함수가 StatementHandle에 대해 호출되었고 이 함수가 호출되었을 때 계속 실행되고 있었습니다. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations 또는 SQLSetPos가 StatementHandle에 대해 호출되고 SQL_NEED_DATA 반환되었습니다. 이 함수는 모든 실행 시 데이터 매개 변수 또는 열에 대한 데이터를 보내기 전에 호출되었습니다. (DM) StatementHandle이 실행된 상태였지만 결과 집합이 StatementHandle과 연결되지 않았습니다. SQLExeceute, SQLExecDirect 또는 SQLMoreResults에 대한 호출은 SQL_PARAM_DATA_AVAILABLE 반환되었지만 SQLParamData 대신 SQLGetData가 호출되었습니다. |
| HY013 | 메모리 관리 오류 | 메모리 조건이 낮기 때문에 기본 메모리 개체에 액세스할 수 없기 때문에 함수 호출을 처리할 수 없습니다. |
| HY090 | 잘못된 문자열 또는 버퍼 길이 | (DM) BufferLength 인수에 지정된 값이 0보다 작습니다. BufferLength 인수에 지정된 값이 4보다 작고, Col_or_Param_Num 인수가 0으로 설정되었으며, 드라이버가 ODBC 2*.x* 드라이버였습니다. |
| HY109 | 커서 위치가 잘못되었습니다. | 삭제되었거나 가져올 수 없는 행에 커서가 배치되었습니다(SQLSetPos, SQLFetch, SQLFetchScroll 또는 SQLBulkOperations). 커서가 전방 전용 커서였고 행 집합 크기가 1보다 큽니다. |
| HY117 | 알 수 없는 트랜잭션 상태로 인해 연결이 일시 중단됩니다. 연결 끊기 및 읽기 전용 함수만 허용됩니다. | (DM) 일시 중단 상태에 대한 자세한 내용은 SQLEndTran 함수를 참조 하세요. |
| HYC00 | 선택적 기능이 구현되지 않음 | 드라이버 또는 데이터 원본은 SQLFetchScroll에서 여러 행이 있는 SQLGetData 사용을 지원하지 않습니다. 이 설명은 SQLGetInfo의 SQL_GETDATA_EXTENSIONS 옵션에 대한 SQL_GD_BLOCK 비트 마스크를 반환하는 드라이버에는 적용되지 않습니다. 드라이버 또는 데이터 원본은 TargetType 인수와 해당 열의 SQL 데이터 형식 조합으로 지정된 변환을 지원하지 않습니다. 이 오류는 열의 SQL 데이터 형식이 드라이버별 SQL 데이터 형식에 매핑된 경우에만 적용됩니다. 드라이버는 ODBC 2*.x*만 지원하며 TargetType 인수는 다음 중 하나입니다. SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT 및 부록 D: 데이터 형식의 C 데이터 형식에 나열된 간격 C 데이터 형식입니다. 드라이버는 3.50 이전의 ODBC 버전만 지원하며 TargetType 인수는 SQL_C_GUID. |
| HYT01 | 연결 제한 시간이 만료됨 | 데이터 원본이 요청에 응답하기 전에 연결 제한 시간이 만료되었습니다. 연결 제한 시간은 SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr를 통해 설정됩니다. |
| IM001 | 드라이버는 이 함수를 지원하지 않습니다. | (DM) StatementHandle에 해당하는 드라이버는 함수를 지원하지 않습니다. |
| IM017 | 비동기 알림 모드에서 폴링을 사용할 수 없습니다. | 알림 모델을 사용할 때마다 폴링이 비활성화됩니다. |
| IM018 | 이 핸들에서 이전 비동기 작업을 완료하기 위해 SQLCompleteAsync 가 호출되지 않았습니다. | 핸들의 이전 함수 호출이 SQL_STILL_EXECUTING 반환하고 알림 모드가 활성화된 경우 사후 처리를 수행하고 작업을 완료하려면 핸들에서 SQLCompleteAsync 를 호출해야 합니다. |
주석
SQLGetData 는 지정된 열의 데이터를 반환합니다. SQLGetData는 SQLFetch, SQLFetchScroll 또는 SQLExtendedFetch에서 결과 집합에서 하나 이상의 행을 가져온 후에만 호출할 수 있습니다. 가변 길이 데이터가 너무 커서 SQLGetData에 대한 단일 호출에서 반환할 수 없는 경우(애플리케이션의 제한으로 인해) SQLGetData는 부분적으로 검색할 수 있습니다. 일부 열은 행에 바인딩하고 다른 열은 SQLGetData를 호출할 수 있지만 일부 제한 사항이 적용됩니다. 자세한 내용은 긴 데이터 가져오기를 참조 하세요.
스트리밍된 출력 매개 변수와 함께 SQLGetData를 사용하는 방법에 대한 자세한 내용은 SQLGetData를 사용하여 출력 매개 변수 검색을 참조 하세요.
SQLGetData 사용
드라이버가 SQLGetData에 대한 확장을 지원하지 않는 경우 함수는 마지막 바인딩된 열보다 큰 숫자가 있는 언바운드 열에 대해서만 데이터를 반환할 수 있습니다. 또한 데이터 행 내에서 SQLGetData에 대한 각 호출에서 Col_or_Param_Num 인수의 값은 이전 호출의 Col_or_Param_Num 값보다 크거나 같아야 합니다. 즉, 열 번호 순서를 늘려 데이터를 검색해야 합니다. 마지막으로, 지원되는 확장이 없으면 행 집합 크기가 1보다 크면 SQLGetData 를 호출할 수 없습니다.
운전자는 이러한 제한 사항을 완화할 수 있습니다. 드라이버에서 완화되는 제한을 확인하기 위해 애플리케이션은 다음 SQL_GETDATA_EXTENSIONS 옵션 중 어떤 것을 사용하여 SQLGetInfo를 호출합니다.
SQL_GD_OUTPUT_PARAMS = 출력 매개 변수 값을 반환하기 위해 SQLGetData 를 호출할 수 있습니다. 자세한 내용은 SQLGetData를 사용하여 출력 매개 변수 검색을 참조하세요.
SQL_GD_ANY_COLUMN. 이 옵션이 반환 되면 마지막 바인딩된 열 앞의 열을 포함하여 언바운드 열에 대해 SQLGetData 를 호출할 수 있습니다.
SQL_GD_ANY_ORDER. 이 옵션이 반환 되면 어떤 순서로든 언바운드 열에 대해 SQLGetData 를 호출할 수 있습니다.
SQL_GD_BLOCK. SQL_GETDATA_EXTENSIONS InfoType에 대해 SQLGetInfo에서 이 옵션을 반환하는 경우 드라이버는 행 집합 크기가 1보다 크면 SQLGetData에 대한 호출을 지원하고 애플리케이션은 SQLGetData를 호출하기 전에 SQL_POSITION 옵션을 사용하여 SQLSetPos를 호출하여 올바른 행에 커서를 배치할 수 있습니다.
SQL_GD_BOUND. 이 옵션이 반환 되면 바인딩된 열과 언바운드 열에 대해 SQLGetData 를 호출할 수 있습니다.
이러한 제한 사항과 이를 완화하는 운전자의 기능에는 두 가지 예외가 있습니다. 첫째, 행 집합 크기가 1보다 크면 SQLGetData 를 정방향 전용 커서에 대해 호출해서는 안 됩니다. 둘째, 드라이버가 책갈피를 지원하는 경우 애플리케이션이 마지막 바인딩된 열 앞의 다른 열에 대해 SQLGetData를 호출하는 것을 허용하지 않더라도 항상 열 0에 대해 SQLGetData를 호출하는 기능을 지원해야 합니다. (애플리케이션이 ODBC 2*.x* 드라이버 로 작업하는 경우SQLGetData는 SQLFetch 호출 후 Col_or_Param_Num 0과 같음으로 호출될 때 책갈피를 반환합니다. SQLFetch는 ODBC 3*.x* 드라이버 관리자에서 SQL_FETCH_NEXT FetchOrientation을 사용하여 SQLExtendedFetch에 매핑되고 Col_or_Param_Num 0인 SQLGetData는 ODBC 3*.x* 드라이버 관리자에서 SQL_GET_BOOKMARK fOption을 사용하여 SQLGetStmtOption에 매핑되므로).
커서가 행에 배치되지 않으므로 SQLGetData는 SQL_ADD 옵션을 사용하여 SQLBulkOperations를 호출하여 삽입된 행의 책갈피를 검색하는 데 사용할 수 없습니다. 애플리케이션은 SQL_ADD 사용하여 SQLBulkOperations를 호출하기 전에 열 0을 바인딩하여 이러한 행에 대한 책갈피를 검색할 수 있습니다. 이 경우 SQLBulkOperations는 바인딩된 버퍼에 책갈피를 반환합니다. 그런 다음 SQL_FETCH_BOOKMARK 사용하여 SQLFetchScroll 을 호출하여 해당 행의 커서 위치를 변경할 수 있습니다.
TargetType 인수가 간격 데이터 형식인 경우 ARD의 SQL_DESC_DATETIME_INTERVAL_PRECISION 및 SQL_DESC_PRECISION 필드에 각각 설정된 기본 간격 선행 전체 자릿수(2) 및 기본 간격 초 정밀도(6)가 데이터에 사용됩니다. TargetType 인수가 SQL_C_NUMERIC 데이터 형식인 경우 ARD의 SQL_DESC_PRECISION 및 SQL_DESC_SCALE 필드에 설정된 기본 전체 자릿수(드라이버 정의) 및 기본 소수 자릿수(0)가 데이터에 사용됩니다. 기본 전체 자릿수 또는 소수 자릿수가 적절하지 않은 경우 애플리케이션은 SQLSetDescField 또는 SQLSetDescRec를 호출하여 적절한 설명자 필드를 명시적으로 설정해야 합니다. SQL_DESC_CONCISE_TYPE 필드를 SQL_C_NUMERIC 설정하고 SQL_ARD_TYPE TargetType 인수를 사용하여 SQLGetData를 호출할 수 있습니다. 그러면 설명자 필드의 전체 자릿수 및 배율 값이 사용됩니다.
참고 항목
ODBC 2*.x*에서 애플리케이션은 TargetType을 SQL_C_DATE, SQL_C_TIME 또는 SQL_C_TIMESTAMP 설정하여 *TargetValuePtr이 날짜, 시간 또는 타임스탬프 구조임을 나타냅니다. ODBC 3*.x*에서 애플리케이션은 TargetType을 SQL_C_TYPE_DATE, SQL_C_TYPE_TIME 또는 SQL_C_TYPE_TIMESTAMP 설정합니다. 필요한 경우 드라이버 관리자는 애플리케이션 및 드라이버 버전에 따라 적절한 매핑을 만듭니다.
파트에서 가변 길이 데이터 검색
SQLGetData 를 사용하여 부분의 가변 길이 데이터를 포함하는 열에서 데이터를 검색할 수 있습니다. 즉, 열의 SQL 데이터 형식 식별자가 변수 길이 형식에 대한 SQL_CHAR, SQL_VARCHAR, SQL_LONGVARCHAR, SQL_WCHAR, SQL_WVARCHAR, SQL_WLONGVARCHAR, SQL_BINARY, SQL_VARBINARY, SQL_LONGVARBINARY 또는 드라이버별 식별자일 때입니다.
부분의 열에서 데이터를 검색하기 위해 애플리케이션은 동일한 열에 대해 SQLGetData를 여러 번 연속해서 호출합니다. 각 호출에서 SQLGetData 는 데이터의 다음 부분을 반환합니다. 문자 데이터의 중간 부분에서 null 종료 문자를 제거하기 위해 주의하여 파트를 재조립하는 것은 애플리케이션의 맡입니다. 반환할 데이터가 더 많거나 버퍼가 종료 문자 에 할당되지 않은 경우 SQLGetData 는 SQL_SUCCESS_WITH_INFO 및 SQLSTATE 01004(잘린 데이터)를 반환합니다. 데이터의 마지막 부분을 반환하면 SQLGetData 는 SQL_SUCCESS 반환합니다. 애플리케이션이 애플리케이션 버퍼의 데이터 양을 알 수 없으므로 열에서 데이터를 검색하기 위해 마지막 유효한 호출에서 SQL_NO_TOTAL 또는 0을 반환할 수 없습니다. 이 후에 SQLGetData가 호출되면 SQL_NO_DATA 반환됩니다. 자세한 내용은 다음 섹션인 "SQLGetData를 사용하여 데이터 검색"을 참조하세요.
가변 길이 책갈피는 SQLGetData에서 파트로 반환할 수 있습니다. 다른 데이터와 마찬가지로 SQLGetData를 호출하여 가변 길이 책갈피를 파트에 반환하면 반환할 데이터가 더 있을 때 SQLSTATE 01004(문자열 데이터, 오른쪽 잘림)와 SQL_SUCCESS_WITH_INFO 반환됩니다. 이는 SQL_ERROR 및 SQLSTATE 22001(문자열 데이터, 오른쪽 잘림)을 반환하는 SQLFetch 또는 SQLFetchScroll 호출에 의해 가변 길이 책갈피가 잘리는 경우와 다릅니다.
SQLGetData 는 부분의 고정 길이 데이터를 반환하는 데 사용할 수 없습니다. SQLGetData가 고정 길이 데이터를 포함하는 열에 대해 행에서 두 번 이상 호출되는 경우 첫 번째 이후의 모든 호출에 대해 SQL_NO_DATA 반환합니다.
스트리밍 출력 매개 변수 검색
드라이버가 스트리밍된 출력 매개 변수를 지원하는 경우 애플리케이션은 작은 버퍼가 있는 SQLGetData를 여러 번 호출하여 큰 매개 변수 값을 검색할 수 있습니다. 스트리밍된 출력 매개 변수에 대한 자세한 내용은 SQLGetData를 사용하여 출력 매개 변수 검색을 참조하세요.
SQLGetData를 사용하여 데이터 검색
지정된 열 에 대한 데이터를 반환하기 위해 SQLGetData 는 다음 단계 시퀀스를 수행합니다.
열에 대한 모든 데이터를 이미 반환한 경우 SQL_NO_DATA 반환합니다.
데이터가 NULL인 경우 *StrLen_or_IndPtr SQL_NULL_DATA 설정합니다. 데이터가 NULL이고 StrLen_or_IndPtr null 포인터 인 경우 SQLGetData 는 SQLSTATE 22002(표시기 변수가 필요하지만 제공되지 않음)를 반환합니다.
열의 데이터가 NULL 이 아니면 SQLGetData 는 3단계로 진행됩니다.
SQL_ATTR_MAX_LENGTH 문 특성이 0이 아닌 값으로 설정된 경우 열에 문자 또는 이진 데이터가 포함되어 있고 SQLGetData가 이전에 열에 대해 호출되지 않은 경우 데이터는 SQL_ATTR_MAX_LENGTH 바이트로 잘립니다.
참고 항목
SQL_ATTR_MAX_LENGTH 문 특성은 네트워크 트래픽을 줄이기 위한 것입니다. 일반적으로 데이터를 네트워크를 통해 반환하기 전에 잘리는 데이터 원본에 의해 구현됩니다. 드라이버 및 데이터 원본은 이를 지원할 필요가 없습니다. 따라서 데이터가 특정 크기로 잘리도록 하려면 애플리케이션에서 해당 크기의 버퍼를 할당하고 BufferLength 인수에서 크기를 지정해야 합니다.
데이터를 TargetType에 지정된 형식으로 변환합니다. 데이터에는 해당 데이터 형식에 대한 기본 전체 자릿수와 크기가 지정됩니다. TargetType이 SQL_ARD_TYPE 경우 ARD의 SQL_DESC_CONCISE_TYPE 필드에 있는 데이터 형식이 사용됩니다. TargetType이 SQL_ARD_TYPE 경우 데이터에는 SQL_DESC_CONCISE_TYPE 필드의 데이터 형식에 따라 ARD의 SQL_DESC_DATETIME_INTERVAL_PRECISION, SQL_DESC_PRECISION 및 SQL_DESC_SCALE 필드의 전체 자릿수와 소수 자릿수가 지정됩니다. 기본 전체 자릿수 또는 소수 자릿수가 적절하지 않은 경우 애플리케이션은 SQLSetDescField 또는 SQLSetDescRec를 호출하여 적절한 설명자 필드를 명시적으로 설정해야 합니다.
데이터가 문자 또는 이진과 같은 가변 길이 데이터 형식으로 변환된 경우 SQLGetData는 데이터의 길이가 BufferLength를 초과하는지 여부를 확인합니다. 문자 데이터 길이(null 종료 문자 포함)가 BufferLength를 초과하면 SQLGetData는 데이터를 BufferLength로 잘라 null 종료 문자의 길이를 줄입니다. 그런 다음, 데이터를 null로 종료합니다. 이진 데이터의 길이가 데이터 버퍼의 길이를 초과하면 SQLGetData는 버퍼렌즈 바이트로 자른다.
제공된 데이터 버퍼가 너무 작아서 null 종료 문자를 보유할 수 없는 경우 SQLGetData 는 SQL_SUCCESS_WITH_INFO 및 SQLSTATE 01004를 반환합니다.
SQLGetData 는 고정 길이 데이터 형식으로 변환된 데이터를 잘라내지 않습니다. *TargetValuePtr 의 길이가 데이터 형식의 크기라고 항상 가정합니다.
변환된(및 잘릴 수 있음) 데이터를 *TargetValuePtr에 배치합니다. SQLGetData는 데이터를 줄 바깥으로 반환할 수 없습니다.
*StrLen_or_IndPtr 데이터 길이를 배치합니다. StrLen_or_IndPtr null 포인터인 경우 SQLGetData는 길이를 반환하지 않습니다.
문자 또는 이진 데이터의 경우 변환 후 및 BufferLength로 인해 잘리기 전의 데이터 길이입니다. 드라이버가 변환 후 데이터의 길이를 확인할 수 없는 경우 긴 데이터가 있는 경우처럼 SQL_SUCCESS_WITH_INFO 반환하고 길이를 SQL_NO_TOTAL 설정합니다. (마지막 호출 SQLGetData 는 항상 0 또는 SQL_NO_TOTAL 아니라 데이터의 길이를 반환해야 합니다.) SQL_ATTR_MAX_LENGTH 문 특성으로 인해 데이터가 잘린 경우 실제 길이와 달리 이 특성의 값은 *StrLen_or_IndPtr 배치됩니다. 이 특성은 변환 전에 서버의 데이터를 자르도록 설계되었으므로 드라이버는 실제 길이를 파악할 방법이 없기 때문입니다. 동일한 열에 대해 SQLGetData를 여러 번 연속으로 호출하는 경우 현재 호출을 시작할 때 사용할 수 있는 데이터의 길이입니다. 즉, 후속 호출마다 길이가 감소합니다.
다른 모든 데이터 형식의 경우 변환 후의 데이터 길이입니다. 즉, 데이터가 변환된 형식의 크기입니다.
변환 중에 유의성이 손실되지 않고 데이터가 잘리는 경우(예: 정수 1로 변환할 때 실수 1.234가 잘리거나) BufferLength가 너무 작기 때문에(예: "abcdef" 문자열이 4바이트 버퍼에 배치됨) SQLGetData는 SQLSTATE 01004(데이터가 잘린) 및 SQL_SUCCESS_WITH_INFO 반환합니다. SQL_ATTR_MAX_LENGTH 문 특성 으로 인한 중요도 손실 없이 데이터가 잘리는 경우 SQLGetData 는 SQL_SUCCESS 반환하고 SQLSTATE 01004(데이터가 잘린 경우)를 반환하지 않습니다.
바인딩된 데이터 버퍼의 내용(SQLGetData가 바인딩된 열에서 호출되는 경우) 및 길이/표시기 버퍼는 SQLGetData가 SQL_SUCCESS 또는 SQL_SUCCESS_WITH_INFO 반환하지 않는 경우 정의되지 않습니다.
SQLGetData에 대한 연속 호출은 요청된 마지막 열에서 데이터를 검색합니다. 이전 오프셋은 유효하지 않습니다. 예를 들어 다음 시퀀스가 수행되는 경우:
SQLGetData(icol=n), SQLGetData(icol=m), SQLGetData(icol=n)
SQLGetData(icol=n)에 대한 두 번째 호출은 n 열의 시작에서 데이터를 검색합니다. 열에 대한 SQLGetData에 대한 이전 호출로 인한 데이터 오프셋은 더 이상 유효하지 않습니다.
설명자 및 SQLGetData
SQLGetData 는 설명자 필드와 직접 상호 작용하지 않습니다.
TargetType이 SQL_ARD_TYPE 경우 ARD의 SQL_DESC_CONCISE_TYPE 필드에 있는 데이터 형식이 사용됩니다. TargetType이 SQL_ARD_TYPE 또는 SQL_C_DEFAULT 경우 데이터에는 SQL_DESC_CONCISE_TYPE 필드의 데이터 형식에 따라 ARD의 SQL_DESC_DATETIME_INTERVAL_PRECISION, SQL_DESC_PRECISION 및 SQL_DESC_SCALE 필드의 전체 자릿수와 크기가 지정됩니다.
코드 예
다음 예제에서 애플리케이션은 SELECT 문을 실행하여 이름, ID 및 전화 번호를 기준으로 정렬된 고객 ID, 이름 및 전화 번호의 결과 집합을 반환합니다. 데이터의 각 행에 대해 SQLFetch를 호출하여 커서를 다음 행에 배치합니다. SQLGetData를 호출하여 가져온 데이터를 검색합니다. 데이터에 대한 버퍼와 반환된 바이트 수는 SQLGetData 호출에 지정됩니다. 마지막으로 각 직원의 이름, ID 및 전화 번호를 출력합니다.
#define NAME_LEN 50
#define PHONE_LEN 50
SQLCHAR szName[NAME_LEN], szPhone[PHONE_LEN];
SQLINTEGER sCustID, cbName, cbAge, cbBirthday;
SQLRETURN retcode;
SQLHSTMT hstmt;
retcode = SQLExecDirect(hstmt,
"SELECT CUSTID, NAME, PHONE FROM CUSTOMERS ORDER BY 2, 1, 3",
SQL_NTS);
if (retcode == SQL_SUCCESS) {
while (TRUE) {
retcode = SQLFetch(hstmt);
if (retcode == SQL_ERROR || retcode == SQL_SUCCESS_WITH_INFO) {
show_error();
}
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){
/* Get data for columns 1, 2, and 3 */
SQLGetData(hstmt, 1, SQL_C_ULONG, &sCustID, 0, &cbCustID);
SQLGetData(hstmt, 2, SQL_C_CHAR, szName, NAME_LEN, &cbName);
SQLGetData(hstmt, 3, SQL_C_CHAR, szPhone, PHONE_LEN,
&cbPhone);
/* Print the row of data */
fprintf(out, "%-5d %-*s %*s", sCustID, NAME_LEN-1, szName,
PHONE_LEN-1, szPhone);
} else {
break;
}
}
}
관련 함수
| 추가 정보 | 참조 |
|---|---|
| 결과 집합의 열에 대한 스토리지 할당 | Sqlbindcol |
| 블록 커서 위치와 관련이 없는 대량 작업 수행 | SQLBulkOperations |
| 문 처리 취소 | SQLCancel |
| SQL 문 실행 | SQLExecDirect |
| 준비된 SQL 문 실행 | SQLExecute |
| 데이터 블록을 가져오거나 결과 집합을 스크롤합니다. | SQLFetchScroll |
| 한 행의 데이터 또는 데이터 블록을 정방향으로 가져오기 | SQLFetch |
| 실행 시 매개 변수 데이터 보내기 | Sqlputdata |
| 커서 위치 지정, 행 집합의 데이터 새로 고침 또는 행 집합의 데이터 업데이트 또는 삭제 | Sqlsetpos |
참고 항목
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기