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);  

Аргументы

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

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

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

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

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

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

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

Возвраты

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

Диагностика

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

SQLSTATE	Error	Description
01000	Общее предупреждение	Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
01004	Строковые данные, усеченные справа	Буфер *ColumnName был недостаточно большим, чтобы вернуть все имя столбца, поэтому имя столбца было усечено. Длина ненадежного имени столбца возвращается в *NameLengthPtr. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
07005	Подготовленная инструкция не спецификация курсора	Оператор, связанный с ОператоромHandle , не вернул результирующий набор. Не было никаких столбцов, которые нужно описать.
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 перед выполнением инструкции.

Комментарии

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

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

Заметка

ODBC поддерживает SQL_NULLABLE_UNKNOWN в качестве расширения, даже если спецификация интерфейса уровня вызова группы open Group и SQL Access Access не указывает параметр для SQLDescribeCol.

Связанные функции

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

См. также

Справочник по API ODBC
Файлы заголовков ODBC