SQLGetDescField 함수

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

Summary
SQLGetDescField 는 디스크립터 레코드의 단일 필드의 현재 설정 또는 값을 반환합니다.

Syntax

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

Arguments

DescriptorHandle
[입력] 디스크립터 핸들.

RecNumber
[입력] 애플리케이션이 정보를 찾는 디스크립터 레코드를 나타냅니다. 디스크립터 레코드는 0부터 번호가 매겨지며, 레코드 번호 0은 북마크 레코드입니다. FieldIdentifier 인자가 헤더 필드를 나타내면 RecNumber는 무시됩니다. RecNumber가 SQL_DESC_COUNT 이하인데 행에 열이나 매개변수 데이터가 포함되어 있지 않으면, SQLGetDescField를 호출하면 필드의 기본 값을 반환합니다. (자세한 내용은 SQLSetDescField의 "디스크립터 필드 초기화"를 참조하세요.)

FieldIdentifier
[입력] 반환할 값의 디스크립터의 필드를 나타냅니다. 자세한 내용은 SQLSetDescField의 "FieldIdentifier Argument" 섹션을 참조하세요.

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 인자를 설정하여 드라이버 매니저에 필드의 성격을 표시합니다. 버퍼길이는 다음과 같은 값을 가질 수 있습니다:

• *ValuePtr 가 문자 문자열에 대한 포인터라면, BufferLength는 문자열 또는 SQL_NTS의 길이입니다.

• *ValuePtr 가 이진 버퍼로 가는 포인터라면, 애플리케이션은 SQL_LEN_BINARY_ATTR(length) 매크로 결과를 BufferLength에 배치합니다. 이로 인해 버퍼길이에 음수가 부여됩니다.

• * ValuePtr 가 문자 문자열이나 이진 문자열이 아닌 다른 값을 가리키는 포인터라면, BufferLength 는 값이 SQL_IS_POINTER 있어야 합니다.

• * ValuePtr 가 고정 길이 데이터 타입을 포함한다면, BufferLength는 적절히 SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT, 또는 SQL_IS_USMALLINT 중 하나입니다.

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

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA, 또는 SQL_INVALID_HANDLE.

RecNumber가 현재 디스크립터 레코드 수를 초과하면 SQL_NO_DATA가 반환됩니다.

SQL_NO_DATA 반환되는 것은 DescriptorHandle 이 IRD 핸들이고 문장이 준비 또는 실행 상태에 있지만 열린 커서가 없을 때 반환됩니다.

진단

SQLGetDescField가 SQL_ERROR 또는 SQL_SUCCESS_WITH_INFO을 반환할 때, SQLGetDiagRec에 HandleType을 SQL_HANDLE_STMT, Handle을 StatementHandle으로 호출하여 관련 SQLSTATE 값을 얻을 수 있습니다. 다음 표는 SQLGetDescField 가 일반적으로 반환하는 SQLSTATE 값들을 나열하며, 각 값이 이 함수의 맥락에서 설명됩니다; 드라이버 매니저가 반환하는 SQLSTATE 설명 앞에 "(DM)"이라는 표기가 붙습니다. 달리 명시되지 않는 한 각 SQLSTATE 값과 연결된 반환 코드는 SQL_ERROR.

SQLSTATE	오류	Description
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 은 IRD로서 StatementHandle 과 연관되어 있었으며, 관련 문장 핸들은 준비되거나 실행되지 않았습니다.
HY010	함수 시퀀스 오류	(DM) DescriptorHandle 은 비동기 실행 함수(이 함수가 아님)가 호출되었고, 이 함수가 호출될 때까지 실행 중이던 StatementHandle 과 연관되어 있었습니다. (DM) DescriptorHandle은 SQLExecute, SQLExecDirect, SQLBulkOperations, 또는 SQLSetPos를 호출하고 반환한 StatementHandle과 연관SQL_NEED_DATA. 이 함수는 모든 실행 시 데이터 매개 변수 또는 열에 대한 데이터를 보내기 전에 호출되었습니다. (DM) DescriptorHandle과 연관된 연결 핸들에 대해 비동기적으로 실행 중인 함수가 호출되었습니다. 이 비동기 함수는 SQLGetDescField 함수가 호출될 때까지 여전히 실행 중이었습니다.
HY013	메모리 관리 오류	메모리 조건이 낮기 때문에 기본 메모리 개체에 액세스할 수 없기 때문에 함수 호출을 처리할 수 없습니다.
HY021	일관성 없는 기술자 정보	SQL_DESC_TYPE와 SQL_DESC_DATETIME_INTERVAL_CODE 필드는 유효한 ODBC SQL 타입, 유효한 드라이버별 SQL 타입(IPD용), 유효한 ODBC C 타입(APD 또는 ARD용)을 형성하지 않습니다.
HY090	잘못된 문자열 또는 버퍼 길이	(DM) *ValuePtr 은 문자 문자열이었고, 버퍼길이 는 0보다 작았습니다.
HY091	잘못된 디스크립터 필드 식별자	FieldIdentifier 는 ODBC에서 정의한 필드가 아니었고, 구현에서 정의된 값도 아니었습니다. FieldIdentifier 는 DescriptorHandle에 대해 정의되지 않았습니다.
HY117	알 수 없는 트랜잭션 상태로 인해 연결이 일시 중단됩니다. 연결 끊기 및 읽기 전용 함수만 허용됩니다.	(DM) 일시 중지 상태에 대한 자세한 내용은 SQLEndTran 함수를 참조하세요.
HYT01	연결 제한 시간이 만료됨	데이터 원본이 요청에 응답하기 전에 연결 제한 시간이 만료되었습니다. 연결 제한 시간은 SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr를 통해 설정됩니다.
IM001	드라이버는 이 함수를 지원하지 않습니다.	(DM) DescriptorHandle 과 연관된 드라이버는 해당 기능을 지원하지 않습니다.

코멘트

애플리케이션은 SQLGetDescField 를 호출하여 디스크립터 레코드의 단일 필드 값을 반환할 수 있습니다. SQLGetDescField를 호출하면 헤더 필드, 레코드 필드, 북마크 필드 등 모든 디스크립터 유형의 필드 설정을 반환할 수 있습니다. 애플리케이션은 SQLGetDescField에 반복적으로 호출함으로써 동일하거나 다른 디스크립터의 여러 필드 설정을 임의의 순서로 얻을 수 있습니다. SQLGetDescField 는 드라이버 정의 디스크립터 필드를 반환하기 위해 호출할 수도 있습니다.

성능 문제로, 애플리케이션은 문장을 실행하기 전에 IRD를 위해 SQLGetDescField 를 호출해서는 안 됩니다.

컬럼 또는 매개변수 데이터의 이름, 데이터 타입, 저장 공간을 설명하는 여러 필드의 설정도 SQLGetDescRec에 한 번의 호출로 가져올 수 있습니다. SQLGetStmtAttr 을 호출하면 디스크립터 헤더 내 단일 필드 설정이 반환되며, 이 필드는 또한 명문 속성입니다. SQLColAttribute, SQLDescribeCol, SQLDescribeParam 필드를 반환합니다.

애플리케이션이 특정 디스크립터 유형에 대해 정의되지 않은 필드의 값을 가져오기 위해 SQLGetDescField 를 호출하면, 함수는 SQL_SUCCESS를 반환하지만 해당 필드의 값은 정의되지 않았습니다. 예를 들어, APD나 ARD의 SQL_DESC_NAME 또는 SQL_DESC_NULLABLE 필드에 대해 SQLGetDescField 를 호출하면 해당 필드의 값은 정의되지 않은 값SQL_SUCCESS 반환됩니다.

애플리케이션이 특정 디스크립터 타입에 대해 정의된 필드의 값을 가져오기 위해 SQLGetDescField 를 호출하면, 기본값이 없고 아직 설정되지 않은 필드의 값을 가져오면, 함수는 SQL_SUCCESS를 반환하지만 반환되는 필드의 값은 정의되지 않았습니다. 디스크립터 필드 초기화 및 필드 설명에 대한 자세한 내용은 SQLSetDescField의 "디스크립터 필드 초기화"를 참조하세요. 설명자에 대한 자세한 내용은 설명자를 참조 하세요.

관련 함수

정보에 대해	보십시오
여러 디스크립터 필드 얻기	SQLGetDescRec 함수
단일 설명자 필드 설정	SQLSetDescField 함수
다중 디스크립터 필드 설정	SQLSetDescRec 함수

관련 콘텐츠

• ODBC API 참고 문헌
• ODBC 헤더 파일