Функция 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