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 |
См. также
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по