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 HandleType 및Handle 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이 StatementHandle과 IRD로 연결되었으며 연결된 문 핸들이 준비되거나 실행되지 않았습니다. |
| 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, SQLDescribeCol 및 SQLDescribeParam 은 레코드 또는 책갈피 필드를 반환합니다.
애플리케이션이 SQLGetDescField를 호출하여 특정 설명자 형식에 대해 정의되지 않은 필드의 값을 검색하는 경우 함수는 SQL_SUCCESS 반환하지만 필드에 대해 반환된 값은 정의되지 않습니다. 예를 들어 APD 또는 ARD의 SQL_DESC_NAME 또는 SQL_DESC_NULLABLE 필드에 대해 SQLGetDescField를 호출하면 SQL_SUCCESS 반환되지만 필드에 대해 정의되지 않은 값이 반환됩니다.
애플리케이션이 SQLGetDescField를 호출하여 특정 설명자 형식에 대해 정의되었지만 기본값이 없고 아직 설정되지 않은 필드의 값을 검색하는 경우 함수는 SQL_SUCCESS 반환하지만 필드에 대해 반환된 값은 정의되지 않습니다. 설명자 필드의 초기화 및 필드 설명에 대한 자세한 내용은 SQLSetDescField의 "설명자 필드 초기화" 를 참조하세요. 설명자에 대한 자세한 내용은 설명자를 참조 하세요.
관련 함수
| 추가 정보 | 참조 |
|---|---|
| 여러 설명자 필드 가져오기 | SQLGetDescRec 함수 |
| 단일 설명자 필드 설정 | SQLSetDescField 함수 |
| 여러 설명자 필드 설정 | SQLSetDescRec 함수 |