Функция SQLDescribeCol

Соответствие
Представлена версия: соответствие стандартам ODBC 1.0: ISO 92

Сводка
SQLDescribeCol возвращает дескриптор результата — название столбца, тип, размер столбца, десятичные цифры и нулевость — для одного столбца в наборе результатов. Эта информация также доступна в полях IRD.

Syntax

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

Arguments

ОператорHandle
[Входные данные] Дескриптор инструкции.

ColumnNumber
[Ввод] Количество столбцов данных результатов, упорядоченных последовательно в возрастающем порядке столбцов, начиная с 1. Аргумент ColumnNumber также можно установить в 0 для описания столбца закладок.

ColumnName
[Выход] Указатель на буфер с нулевой терминацией для возврата имени столбца. Это значение считывается из SQL_DESC_NAME поля IRD. Если столбец безымянен или имя столбца невозможно определить, драйвер возвращает пустую строку.

Если ColumnName — NULL, NameLengthPtr всё равно вернёт общее количество символов (за исключением символа null-termination для данных о символах), доступных для возврата в буфере, на который указывает ColumnName.

BufferLength
[Ввод] Длина буфера *ColumnName , в символах.

NameLengthPtr
[Выход] Указатель на буфер, в котором можно вернуть общее количество символов (за исключением нулевой терминации), доступных для возврата в *ColumnName. Если количество доступных для возврата символов больше или равно BufferLength, имя столбца в *ColumnName усекается до BufferLength минус длина символа null-termination.

DataTypePtr
[Выход] Указатель на буфер для возврата SQL-данных столбца. Это значение считывается из SQL_DESC_CONCISE_TYPE поля IRD. Это будет одним из значений в SQL Data Types или специфическим для драйвера 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 driver.

Если columnNumber равно 0 (для столбца закладки), SQL_BINARY возвращается в *DataTypePtr для закладок переменной длины. (SQL_INTEGER возвращается, если закладки используются ODBC 3.приложение x , работающее с ODBC 2.драйвер x или ODBC 2.приложение x , работающее с ODBC 3.x driver.)

Для получения дополнительной информации об этих типах данных см. Типы данных SQL в Приложении D: Типы данных. Сведения о типах данных SQL для конкретного драйвера см. в документации по драйверу.

ColumnSizePtr
[Выход] Указатель на буфер для возврата размера столбца (в символах) на источнике данных. Если размер столбца определить невозможно, драйвер возвращает 0. Дополнительные сведения о размере столбца см. в разделе "Размер столбца", "Десятичные цифры", " Длина октета" и "Размер отображения" в приложении D: Типы данных.

DecimalDigitsPtr
[Выход] Указатель на буфер для возврата количества десятичных цифр столбца на источнике данных. Если количество десятичных цифр невозможно определить или не применимо, драйвер возвращает 0. Для получения дополнительной информации о десятичных цифрах см. разделы «Размер столбца», «Десятичные цифры», «Длина октета передачи» и «Размер отображения » в Приложении D: «Типы данных».

NullablePtr
[Выход] Указатель на буфер, в котором нужно вернуть значение, указывающее, допускает ли столбец значения NULL. Это значение считывается из SQL_DESC_NULLABLE поля IRD. Допустимы следующие значения:

SQL_NO_NULLS: Столбец не допускает значения NULL.

SQL_NULLABLE: Столбец допускает значения NULL.

SQL_NULLABLE_UNKNOWN: Драйвер не может определить, допускает ли столбец значения NULL.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR или SQL_INVALID_HANDLE.

Diagnostics

Когда SQLDescribeCol возвращает либо SQL_ERROR, либо SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить, вызвав SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и HandleHandle of StatementHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращает SQLDescribeCol , и каждое из них объясняется в контексте этой функции; обозначение «(DM)» предшествует описаниям SQLSTATE, возвращаемым менеджером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.

SQLSTATE	Error	Description
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 для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину.
HY001	Сбой при выделении памяти	Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции.
HY008	Операция отменена	Асинхронная обработка была включена для ОператораHandle. Функция была вызвана и до завершения выполнения, SQLCancel или SQLCancelHandle была вызвана на ОператорHandle. Затем функция снова была вызвана на ОператорHandle. Функция была вызвана и до завершения выполнения SQLCancel или SQLCancelHandle была вызвана оператором StatementHandle из другого потока в многопотоковом приложении.
HY010	Ошибка последовательности функций	(DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ОператоромHandle. Эта асинхронная функция всё ещё выполнялась, когда был вызван SQLDescribeCol . (DM) SQLExecute, SQLExecDirect или SQLMoreResults был вызван для ОператораHandle и возвращен SQL_PARAM_DATA_AVAILABLE. Эта функция была вызвана до получения данных для всех потоковых параметров. (DM) асинхронно выполняющаяся функция (не эта) была вызвана для StatementHandle и по-прежнему выполнялась при вызове этой функции. (DM) Функция была вызвана до вызова SQLPrepare, SQLExecute или каталожной функции на дескрипторе оператора. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos были вызваны для ОператораHandle и возвращены SQL_NEED_DATA. Эта функция была вызвана до отправки данных для всех параметров выполнения или столбцов.
HY013	Ошибка управления памятью	Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти.
HY090	Недопустимая длина строки или буфера	(DM) Значение, указанное для аргумента BufferLength , было меньше 0.
HY117	Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения.	(DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function.
HYT01	Время ожидания для подключения истекло	Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Драйвер не поддерживает эту функцию	(DM) Драйвер, связанный с StatementHandle , не поддерживает функцию.
IM017	Опрос отключен в асинхронном режиме уведомлений	При использовании модели уведомлений опрос отключается.
IM018	SQLCompleteAsync не был вызван для выполнения предыдущей асинхронной операции с этим дескриптором.	Если предыдущий вызов функции дескриптора возвращает SQL_STILL_EXECUTING и если включен режим уведомлений, sqlCompleteAsync должен вызываться на дескрипторе для выполнения последующей обработки и завершения операции.

SQLDescribeCol может возвращать любой SQLSTATE, который может быть возвращён SQLPrepare или SQLExecute при вызове после SQLPrepare и до SQLExecute, в зависимости от того, когда источник данных оценивает SQL-оператор, связанный с дескриптором оператора.

По соображениям производительности приложение не должно вызывать SQLDescribeCol перед выполнением оператора.

Comments

Приложение обычно вызывает SQLDescribeCol после вызова SQLPrepare и до или после связанного вызова SQLExecute. Приложение также может вызывать SQLDescribeCol после вызова SQLExecDirect. Дополнительные сведения см. в разделе метаданных результирующих наборов.

SQLDescribeCol получает имя, тип и длину столбца, сгенерированные оператором SELECT . Если столбец — выражение, *ColumnName — это либо пустая строка, либо имя, определённое драйвером.

Замечание

ODBC поддерживает SQL_NULLABLE_UNKNOWN как расширение, хотя спецификации Open Group и SQL Access Group Call Level Interface не указывает опцию для SQLDescribeCol.

Сведения о	Смотри
Привязка буфера к столбцу в результирующем наборе	SQLBindCol
Отмена обработки инструкций	SQLCancel
Возврат сведений о столбце в результирующем наборе	SQLColAttribute
Получение нескольких строк данных	SQLFetch
Возврат количества столбцов результатов	SQLNumResultCols
Подготовка инструкции для выполнения	SQLPrepare

Кері байланыс

Бет пайдалы болды ма?

Last updated on 2026-08-24