SQLDescribeCol 함수

규칙
버전 소개: ODBC 1.0 표준 준수: ISO 92

요약
SQLDescribeCol 은 결과 집합의 한 열에 대해 결과 설명자(열 이름, 형식, 열 크기, 소수 자릿수 및 null 허용 여부)를 반환합니다. 이 정보는 IRD의 필드에서도 사용할 수 있습니다.

구문

  
SQLRETURN SQLDescribeCol(  
      SQLHSTMT       StatementHandle,  
      SQLUSMALLINT   ColumnNumber,  
      SQLCHAR *      ColumnName,  
      SQLSMALLINT    BufferLength,  
      SQLSMALLINT *  NameLengthPtr,  
      SQLSMALLINT *  DataTypePtr,  
      SQLULEN *      ColumnSizePtr,  
      SQLSMALLINT *  DecimalDigitsPtr,  
      SQLSMALLINT *  NullablePtr);  

인수

StatementHandle
[입력] 문 핸들입니다.

ColumnNumber
[입력] 1부터 시작하여 열 순서를 늘이면서 순차적으로 정렬된 결과 데이터의 열 수입니다. ColumnNumber 인수를 0으로 설정하여 책갈피 열을 설명할 수도 있습니다.

ColumnName
[출력] 열 이름을 반환할 null로 끝나는 버퍼에 대한 포인터입니다. 이 값은 IRD의 SQL_DESC_NAME 필드에서 읽습니다. 열이 명명되지 않거나 열 이름을 확인할 수 없는 경우 드라이버는 빈 문자열을 반환합니다.

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

BufferLength
[입력] *ColumnName 버퍼의 길이(문자)입니다.

NameLengthPtr
[출력] *ColumnName에서 반환할 수 있는 총 문자 수(null 종료 제외)를 반환할 버퍼에 대한 포인터입니다. 반환할 수 있는 문자 수가 BufferLength보다 크거나 같으면 *ColumnName의 열 이름이 BufferLength에서 null 종료 문자의 길이를 뺀 값으로 잘립니다.

DataTypePtr
[출력] 열의 SQL 데이터 형식을 반환할 버퍼에 대한 포인터입니다. 이 값은 IRD의 SQL_DESC_CONCISE_TYPE 필드에서 읽습니다. 이는 SQL 데이터 형식의 값 중 하나이거나 드라이버별 SQL 데이터 형식입니다. 데이터 형식을 확인할 수 없는 경우 드라이버는 SQL_UNKNOWN_TYPE 반환합니다.

ODBC 3에서.x, SQL_TYPE_DATE, SQL_TYPE_TIME 또는 SQL_TYPE_TIMESTAMP 각각 날짜, 시간 또는 타임스탬프 데이터에 대해 *DataTypePtr로 반환되고 ODBC 2에서는 반환됩니다.x, SQL_DATE, SQL_TIME 또는 SQL_TIMESTAMP 반환됩니다. 드라이버 관리자는 ODBC 2일 때 필요한 매핑을 수행합니다.x 애플리케이션이 ODBC 3에서 작동합니다.x 드라이버 또는 ODBC 3인 경우x 애플리케이션이 ODBC 2에서 작동합니다.x 드라이버입니다.

ColumnNumber가 책갈피 열의 경우 0과 같으면 변수 길이 책갈피의 경우 *DataTypePtr에 SQL_BINARY 반환됩니다. (SQL_INTEGER ODBC 3에서 책갈피를 사용하는 경우 반환됩니다.ODBC 2를 사용하는 x 애플리케이션입니다.x 드라이버 또는 ODBC 2.ODBC 3을 사용하는 x 애플리케이션입니다.x driver.)

이러한 데이터 형식에 대한 자세한 내용은 부록 D: 데이터 형식의 SQL 데이터 형식을 참조하세요. 드라이버별 SQL 데이터 형식에 대한 자세한 내용은 드라이버 설명서를 참조하세요.

ColumnSizePtr
[출력] 데이터 원본에서 열의 크기를 문자 단위로 반환할 버퍼에 대한 포인터입니다. 열 크기를 확인할 수 없는 경우 드라이버는 0을 반환합니다. 열 크기에 대한 자세한 내용은 열 크기, 10진수, 8진수 길이 전송 및 부록 D: 데이터 형식의 표시 크기를 참조하세요.

DecimalDigitsPtr
[출력] 데이터 원본에서 열의 10진수 수를 반환할 버퍼에 대한 포인터입니다. 소수 자릿수를 확인할 수 없거나 적용할 수 없는 경우 드라이버는 0을 반환합니다. 10진수에 대한 자세한 내용은 열 크기, 10진수, 8진수 전송 길이 및 부록 D: 데이터 형식의 표시 크기를 참조하세요.

NullablePtr
[출력] 열에서 NULL 값을 허용하는지 여부를 나타내는 값을 반환할 버퍼에 대한 포인터입니다. 이 값은 IRD의 SQL_DESC_NULLABLE 필드에서 읽습니다. 값은 다음 중 하나입니다.

SQL_NO_NULLS: 열에서 NULL 값을 허용하지 않습니다.

SQL_NULLABLE: 열에서 NULL 값을 허용합니다.

SQL_NULLABLE_UNKNOWN: 드라이버가 열에서 NULL 값을 허용하는지 여부를 확인할 수 없습니다.

반품

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR 또는 SQL_INVALID_HANDLE.

진단

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

SQLSTATE	Error	설명
01000	일반 경고	드라이버 관련 정보 메시지입니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다.
01004	문자열 데이터, 오른쪽 잘림	버퍼 *ColumnName 이 전체 열 이름을 반환할 만큼 크지 않아 열 이름이 잘렸습니다. 신뢰할 수 없는 열 이름의 길이는 *NameLengthPtr에서 반환됩니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다.
07005	커서 사양이 아닌 준비된 문	StatementHandle과 연결된 문이 결과 집합을 반환하지 않았습니다. 설명할 열이 없었습니다.
07009	설명자 인덱스가 잘못되었습니다.	(DM) ColumnNumber 인수에 대해 지정된 값이 0이고 SQL_ATTR_USE_BOOKMARKS 문 옵션이 SQL_UB_OFF. ColumnNumber 인수에 대해 지정된 값이 결과 집합의 열 수보다 큽니다.
08S01	통신 링크 실패	드라이버와 드라이버가 연결된 데이터 원본 간의 통신 링크는 함수가 처리를 완료하기 전에 실패했습니다.
HY000	일반 오류	특정 SQLSTATE가 없고 구현별 SQLSTATE가 정의되지 않은 오류가 발생했습니다. *MessageText 버퍼의 SQLGetDiagRec에서 반환된 오류 메시지는 오류와 그 원인을 설명합니다.
HY001	메모리 할당 실패	드라이버가 함수 실행 또는 완료를 지원하는 데 필요한 메모리를 할당할 수 없습니다.
HY008	작업이 취소됨	StatementHandle에 대해 비동기 처리를 사용하도록 설정했습니다. 함수가 호출되었고 실행이 완료되기 전에 StatementHandle에서 SQLCancel 또는 SQLCancelHandle이 호출되었습니다. 그런 다음 StatementHandle에서 함수가 다시 호출되었습니다. 함수가 호출되었고 실행을 완료하기 전에 다중 스레드 애플리케이션의 다른 스레드에서 StatementHandle에서 SQLCancel 또는 SQLCancelHandle이 호출되었습니다.
HY010	함수 시퀀스 오류	(DM) StatementHandle과 연결된 연결 핸들에 대해 비동기적으로 실행되는 함수가 호출되었습니다. SQLDescribeCol이 호출되었을 때 이 비동기 함수는 여전히 실행 중입니다. (DM) SQLExecute, SQLExecDirect 또는 SQLMoreResults가 StatementHandle에 대해 호출되고 SQL_PARAM_DATA_AVAILABLE 반환되었습니다. 이 함수는 모든 스트리밍된 매개 변수에 대해 데이터를 검색하기 전에 호출되었습니다. (DM) 이 함수가 아닌 비동기 실행 함수가 StatementHandle에 대해 호출되었고 이 함수가 호출되었을 때 계속 실행되고 있었습니다. (DM) 이 함수는 문 핸들에서 SQLPrepare, SQLExecute 또는 카탈로그 함수를 호출하기 전에 호출되었습니다. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations 또는 SQLSetPos가 StatementHandle에 대해 호출되고 SQL_NEED_DATA 반환되었습니다. 이 함수는 모든 실행 시 데이터 매개 변수 또는 열에 대한 데이터를 보내기 전에 호출되었습니다.
HY013	메모리 관리 오류	메모리 조건이 낮기 때문에 기본 메모리 개체에 액세스할 수 없기 때문에 함수 호출을 처리할 수 없습니다.
HY090	잘못된 문자열 또는 버퍼 길이	(DM) BufferLength 인수에 지정된 값이 0보다 작습니다.
HY117	알 수 없는 트랜잭션 상태로 인해 연결이 일시 중단됩니다. 연결 끊기 및 읽기 전용 함수만 허용됩니다.	(DM) 일시 중단 상태에 대한 자세한 내용은 SQLEndTran 함수를 참조 하세요.
HYT01	연결 제한 시간이 만료됨	데이터 원본이 요청에 응답하기 전에 연결 제한 시간이 만료되었습니다. 연결 제한 시간은 SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr를 통해 설정됩니다.
IM001	드라이버는 이 함수를 지원하지 않습니다.	(DM) StatementHandle과 연결된 드라이버는 함수를 지원하지 않습니다.
IM017	비동기 알림 모드에서 폴링을 사용할 수 없습니다.	알림 모델을 사용할 때마다 폴링이 비활성화됩니다.
IM018	이 핸들에서 이전 비동기 작업을 완료하기 위해 SQLCompleteAsync 가 호출되지 않았습니다.	핸들의 이전 함수 호출이 SQL_STILL_EXECUTING 반환하고 알림 모드가 활성화된 경우 사후 처리를 수행하고 작업을 완료하려면 핸들에서 SQLCompleteAsync 를 호출해야 합니다.

SQLDescribeCol은 데이터 원본이 문 핸들과 연결된 SQL 문을 평가하는 시기에 따라 SQLPrepare 이후 및 SQLExecute 이전에 호출될 때 SQLPrepare 또는 SQLExecute에서 반환할 수 있는 모든 SQLSTATE를 반환할 수 있습니다.

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

주석

애플리케이션은 일반적으로 SQLPrepare 호출 후 및 SQLExecute에 대한 연결된 호출 전후에 SQLDescribeCol을 호출합니다. 애플리케이션은 SQLExecDirect를 호출한 후 SQLDescribeCol을 호출할 수도 있습니다. 자세한 내용은 결과 집합 메타데이터를 참조하세요.

SQLDescribeCol은 SELECT 문에 의해 생성된 열 이름, 형식 및 길이를 검색합니다. 열이 식인 경우 *ColumnName 은 빈 문자열 또는 드라이버 정의 이름입니다.

참고 항목

ODBC는 열기 그룹 및 SQL 액세스 그룹 호출 수준 인터페이스 사양에서 SQLDescribeCol에 대한 옵션을 지정하지 않더라도 SQL_NULLABLE_UNKNOWN 확장으로 지원합니다.

관련 함수

추가 정보	참조
결과 집합의 열에 버퍼 바인딩	Sqlbindcol
문 처리 취소	SQLCancel
결과 집합의 열에 대한 정보 반환	SQLColAttribute
여러 행의 데이터 가져오기	SQLFetch
결과 집합 열 수 반환	SQLNumResultCols
실행을 위한 문 준비	SQLPrepare

참고 항목

ODBC API 참조
ODBC 헤더 파일