다음을 통해 공유


SQLGetDescField 함수

규칙
도입된 버전: ODBC 3.0 표준 준수: ISO 92

요약
SQLGetDescField 는 설명자 레코드의 단일 필드의 현재 설정 또는 값을 반환합니다.

구문

  
SQLRETURN SQLGetDescField(  
     SQLHDESC        DescriptorHandle,  
     SQLSMALLINT     RecNumber,  
     SQLSMALLINT     FieldIdentifier,  
     SQLPOINTER      ValuePtr,  
     SQLINTEGER      BufferLength,  
     SQLINTEGER *    StringLengthPtr);  

인수

DescriptorHandle
[입력] 설명자 핸들입니다.

RecNumber
[입력] 애플리케이션이 정보를 검색하는 설명자 레코드를 나타냅니다. 설명자 레코드는 0부터 번호가 매겨지고 레코드 번호 0은 책갈피 레코드입니다. FieldIdentifier 인수가 머리글 필드를 나타내는 경우 RecNumber는 무시됩니다. RecNumber가 SQL_DESC_COUNT 작거나 같지만 행에 열 또는 매개 변수에 대한 데이터가 포함되지 않은 경우 SQLGetDescField를 호출하면 필드의 기본값이 반환됩니다. (자세한 내용은 에서 "설명자 필드 초기화" 를 참조하세요.SQLSetDescField.)

FieldIdentifier
[입력] 값을 반환할 설명자의 필드를 나타냅니다. 자세한 내용은 SQLSetDescField의 "FieldIdentifier 인수" 섹션 을 참조하세요.

ValuePtr
[출력] 설명자 정보를 반환할 버퍼에 대한 포인터입니다. 데이터 형식은 FieldIdentifier값에 따라 달라집니다.

ValuePtr이 정수 형식인 경우 애플리케이션은 SQLULEN 버퍼를 사용하고 이 함수를 호출하기 전에 값을 0으로 초기화해야 합니다. 일부 드라이버는 버퍼의 하위 32비트 또는 16비트만 쓰고 상위 순서 비트를 변경하지 않고 그대로 둘 수 있기 때문에 이 함수를 호출해야 합니다.

ValuePtr이 NULL인 경우 StringLengthPtr은 ValuePtr가 가리키는 버퍼에서 반환할 수 있는 총 바이트 수(문자 데이터의 null 종료 문자 제외)를 계속 반환합니다.

BufferLength
[입력] FieldIdentifier가 ODBC 정의 필드이고 ValuePtr가 문자열 또는 이진 버퍼를 가리키는 경우 이 인수는 *ValuePtr의 길이여야 합니다. FieldIdentifier가 ODBC 정의 필드이고 *ValuePtr이 정수이면 BufferLength가 무시됩니다. *ValuePtr의 값이 유니코드 데이터 형식인 경우(SQLGetDescFieldW를 호출할 때) BufferLength 인수는 짝수여야 합니다.

FieldIdentifier가 드라이버 정의 필드인 경우 애플리케이션은 BufferLength 인수를 설정하여 드라이버 관리자에 대한 필드의 특성을 나타냅니다. BufferLength 는 다음 값을 가질 수 있습니다.

  • *ValuePtr이 문자열에 대한 포인터인 경우 BufferLength는 문자열 또는 SQL_NTS 길이입니다.

  • *ValuePtr이 이진 버퍼에 대한 포인터인 경우 애플리케이션은 bufferLength에 SQL_LEN_BINARY_ATTR(길이) 매크로의 결과를 배치합니다. 그러면 BufferLength에 음수 값이 배치됩니다.

  • *ValuePtr이 문자열이나 이진 문자열이 아닌 값에 대한 포인터인 경우 BufferLength에는 SQL_IS_POINTER 값이 있어야 합니다.

  • *ValuePtr에 고정 길이 데이터 형식이 포함된 경우 BufferLength는 적절하게 SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT 또는 SQL_IS_USMALLINT.

StringLengthPtr
[출력] *ValuePtr에서 반환할 수 있는 총 바이트 수(null 종료 문자에 필요한 바이트 수 제외)를 반환할 버퍼에 대한 포인터입니다.

반품

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA 또는 SQL_INVALID_HANDLE.

RecNumber가 현재 설명자 레코드 수보다 큰 경우 SQL_NO_DATA 반환됩니다.

DescriptorHandle이 IRD 핸들이고 문이 준비되거나 실행된 상태이지만 연결된 열린 커서가 없는 경우 SQL_NO_DATA 반환됩니다.

진단

SQLGetDescField가 SQL_ERROR 또는 SQL_SUCCESS_WITH_INFO 반환하는 경우 SQL_HANDLE_STMT HandleTypeHandle of StatementHandle을 사용하여 SQLGetDiagRec 를 호출하여 관련 SQLSTATE 값을 가져올 수 있습니다. 다음 표에서는 SQLGetDescField에서 일반적으로 반환되는 SQLSTATE 값을 나열하고 이 함수의 컨텍스트에서 각각에 대해 설명합니다. 표기법 "(DM)"은 드라이버 관리자가 반환한 SQLSTATE에 대한 설명 앞에 나와 있습니다. 달리 명시되지 않는 한 각 SQLSTATE 값과 연결된 반환 코드는 SQL_ERROR.

SQLSTATE Error 설명
01000 일반 경고 드라이버 관련 정보 메시지입니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다.
01004 문자열 데이터, 오른쪽 잘림 버퍼 *ValuePtr 이 전체 설명자 필드를 반환할 만큼 크지 않아 필드가 잘렸습니다. 신뢰할 수 없는 설명자 필드의 길이는 *StringLengthPtr에서 반환됩니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다.
07009 설명자 인덱스가 잘못되었습니다. (DM) RecNumber 인수가 0이고, SQL_ATTR_USE_BOOKMARK 문 특성이 SQL_UB_OFF, DescriptorHandle 인수가 IRD 핸들이었습니다. (설명자가 문 핸들과 연결된 경우에만 명시적으로 할당된 설명자에 대해 이 오류를 반환할 수 있습니다.)

FieldIdentifier 인수는 레코드 필드이고 RecNumber 인수는 0이고 DescriptorHandle 인수는 IPD 핸들이었습니다.

RecNumber 인수가 0보다 작습니다.
08S01 통신 링크 실패 드라이버와 드라이버가 연결된 데이터 원본 간의 통신 링크는 함수가 처리를 완료하기 전에 실패했습니다.
HY000 일반 오류 특정 SQLSTATE가 없고 구현별 SQLSTATE가 정의되지 않은 오류가 발생했습니다. *MessageText 버퍼의 SQLGetDiagRec에서 반환된 오류 메시지는 오류와 그 원인을 설명합니다.
HY001 메모리 할당 오류 드라이버가 함수 실행 또는 완료를 지원하는 데 필요한 메모리를 할당할 수 없습니다.
HY007 연결된 문이 준비되지 않았습니다. DescriptorHandle이 StatementHandleIRD로 연결되었으며 연결된 문 핸들이 준비되거나 실행되지 않았습니다.
HY010 함수 시퀀스 오류 (DM) DescriptorHandle은 비동기 실행 함수(이 함수가 아님)가 호출되고 이 함수가 호출될 때 여전히 실행 중인 StatementHandle과 연결되었습니다.

(DM) DescriptorHandle은 SQLExecute, SQLExecDirect, SQLBulkOperations 또는 SQLSetPos가 호출되어 SQL_NEED_DATA 반환된 StatementHandle과 연결되었습니다. 이 함수는 모든 실행 시 데이터 매개 변수 또는 열에 대한 데이터를 보내기 전에 호출되었습니다.

(DM) DescriptorHandle과 연결된 연결 핸들에 대해 비동기적으로 실행되는 함수가 호출되었습니다. 이 비동기 함수는 SQLGetDescField 함수가 호출되었을 때 계속 실행되었습니다.
HY013 메모리 관리 오류 메모리 조건이 낮기 때문에 기본 메모리 개체에 액세스할 수 없기 때문에 함수 호출을 처리할 수 없습니다.
HY021 일관되지 않은 설명자 정보 SQL_DESC_TYPE 및 SQL_DESC_DATETIME_INTERVAL_CODE 필드는 유효한 ODBC SQL 형식, 유효한 드라이버별 SQL 형식(IPD의 경우) 또는 유효한 ODBC C 형식(APD 또는 ARD의 경우)을 형성하지 않습니다.
HY090 잘못된 문자열 또는 버퍼 길이 (DM) *ValuePtr 은 문자열이고 BufferLength 는 0보다 작습니다.
HY091 설명자 필드 식별자가 잘못되었습니다. FieldIdentifier 는 ODBC 정의 필드가 아니며 구현 정의 값이 아닙니다.

DescriptorHandle에 대해 FieldIdentifier정의되지 않았습니다.
HY117 알 수 없는 트랜잭션 상태로 인해 연결이 일시 중단됩니다. 연결 끊기 및 읽기 전용 함수만 허용됩니다. (DM) 일시 중단 상태에 대한 자세한 내용은 SQLEndTran 함수를 참조 하세요.
HYT01 연결 제한 시간이 만료됨 데이터 원본이 요청에 응답하기 전에 연결 제한 시간이 만료되었습니다. 연결 제한 시간은 SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr를 통해 설정됩니다.
IM001 드라이버는 이 함수를 지원하지 않습니다. (DM) DescriptorHandle연결된 드라이버는 함수를 지원하지 않습니다.

주석

애플리케이션은 SQLGetDescField를 호출하여 설명자 레코드의 단일 필드 값을 반환할 수 있습니다. SQLGetDescField대한 호출은 헤더 필드, 레코드 필드 및 책갈피 필드를 포함하여 설명자 형식의 모든 필드 설정을 반환할 수 있습니다. 애플리케이션은 SQLGetDescField를 반복적으로 호출하여 동일하거나 다른 설명자에서 임의의 순서로 여러 필드의 설정을 가져올 수 있습니다. 드라이버 정의 설명자 필드를 반환하기 위해 SQLGetDescField 를 호출할 수도 있습니다.

성능상의 이유로 애플리케이션은 문을 실행하기 전에 IRD에 대해 SQLGetDescField를 호출해서는 안 됩니다.

열 또는 매개 변수 데이터의 이름, 데이터 형식 및 스토리지를 설명하는 여러 필드의 설정을 SQLGetDescRec에 대한 단일 호출로 검색할 수도 있습니다. 설명자 헤더에서 문 특성이기도 한 단일 필드의 설정을 반환하기 위해 SQLGetStmtAttr 을 호출할 수 있습니다. SQLColAttribute, SQLDescribeColSQLDescribeParam 은 레코드 또는 책갈피 필드를 반환합니다.

애플리케이션이 SQLGetDescField를 호출하여 특정 설명자 형식에 대해 정의되지 않은 필드의 값을 검색하는 경우 함수는 SQL_SUCCESS 반환하지만 필드에 대해 반환된 값은 정의되지 않습니다. 예를 들어 APD 또는 ARD의 SQL_DESC_NAME 또는 SQL_DESC_NULLABLE 필드에 대해 SQLGetDescField를 호출하면 SQL_SUCCESS 반환되지만 필드에 대해 정의되지 않은 값이 반환됩니다.

애플리케이션이 SQLGetDescField를 호출하여 특정 설명자 형식에 대해 정의되었지만 기본값이 없고 아직 설정되지 않은 필드의 값을 검색하는 경우 함수는 SQL_SUCCESS 반환하지만 필드에 대해 반환된 값은 정의되지 않습니다. 설명자 필드의 초기화 및 필드 설명에 대한 자세한 내용은 SQLSetDescField의 "설명자 필드 초기화" 를 참조하세요. 설명자에 대한 자세한 내용은 설명자를 참조 하세요.

추가 정보 참조
여러 설명자 필드 가져오기 SQLGetDescRec 함수
단일 설명자 필드 설정 SQLSetDescField 함수
여러 설명자 필드 설정 SQLSetDescRec 함수

참고 항목

ODBC API 참조
ODBC 헤더 파일