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.

설명

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를 호출할 수 있습니다. 그러면 설명자 필드의 전체 자릿수 및 배율 값이 사용됩니다.

파트에서 가변 길이 데이터 검색

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 는 다음 단계 시퀀스를 수행합니다.

1. 열에 대한 모든 데이터를 이미 반환한 경우 SQL_NO_DATA 반환합니다.

2. 데이터가 NULL인 경우 *StrLen_or_IndPtr SQL_NULL_DATA 설정합니다. 데이터가 NULL이고 StrLen_or_IndPtr null 포인터 인 경우 SQLGetData 는 SQLSTATE 22002(표시기 변수가 필요하지만 제공되지 않음)를 반환합니다.

   열의 데이터가 NULL 이 아니면 SQLGetData 는 3단계로 진행됩니다.

3. SQL_ATTR_MAX_LENGTH 문 특성이 0이 아닌 값으로 설정된 경우 열에 문자 또는 이진 데이터가 포함되어 있고 SQLGetData가 이전에 열에 대해 호출되지 않은 경우 데이터는 SQL_ATTR_MAX_LENGTH 바이트로 잘립니다.

   참고 항목

   SQL_ATTR_MAX_LENGTH 문 특성은 네트워크 트래픽을 줄이기 위한 것입니다. 일반적으로 데이터를 네트워크를 통해 반환하기 전에 잘리는 데이터 원본에 의해 구현됩니다. 드라이버 및 데이터 원본은 이를 지원할 필요가 없습니다. 따라서 데이터가 특정 크기로 잘리도록 하려면 애플리케이션에서 해당 크기의 버퍼를 할당하고 BufferLength 인수에서 크기를 지정해야 합니다.

4. 데이터를 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를 호출하여 적절한 설명자 필드를 명시적으로 설정해야 합니다.

5. 데이터가 문자 또는 이진과 같은 가변 길이 데이터 형식으로 변환된 경우 SQLGetData는 데이터의 길이가 BufferLength를 초과하는지 여부를 확인합니다. 문자 데이터 길이(null 종료 문자 포함)가 BufferLength를 초과하면 SQLGetData는 데이터를 BufferLength로 잘라 null 종료 문자의 길이를 줄입니다. 그런 다음, 데이터를 null로 종료합니다. 이진 데이터의 길이가 데이터 버퍼의 길이를 초과하면 SQLGetData는 버퍼렌즈 바이트로 자른다.

   제공된 데이터 버퍼가 너무 작아서 null 종료 문자를 보유할 수 없는 경우 SQLGetData 는 SQL_SUCCESS_WITH_INFO 및 SQLSTATE 01004를 반환합니다.

   SQLGetData 는 고정 길이 데이터 형식으로 변환된 데이터를 잘라내지 않습니다. *TargetValuePtr 의 길이가 데이터 형식의 크기라고 항상 가정합니다.

6. 변환된(및 잘릴 수 있음) 데이터를 *TargetValuePtr에 배치합니다. SQLGetData는 데이터를 줄 바깥으로 반환할 수 없습니다.

7. *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를 여러 번 연속으로 호출하는 경우 현재 호출을 시작할 때 사용할 수 있는 데이터의 길이입니다. 즉, 후속 호출마다 길이가 감소합니다.

   • 다른 모든 데이터 형식의 경우 변환 후의 데이터 길이입니다. 즉, 데이터가 변환된 형식의 크기입니다.

8. 변환 중에 유의성이 손실되지 않고 데이터가 잘리는 경우(예: 정수 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;  
      }  
   }  
}  

관련 함수

참고 항목

ODBC API 참조
ODBC 헤더 파일
SQLGetData를 사용하여 출력 매개 변수 검색