Функция SQLGetDescField

Соответствие
Введенная версия: Соответствие стандартам ODBC 3.0: ISO 92

Сводка
SQLGetDescField возвращает текущую настройку или значение одного поля записи дескриптора.

Syntax

  
SQLRETURN SQLGetDescField(  
     SQLHDESC        DescriptorHandle,  
     SQLSMALLINT     RecNumber,  
     SQLSMALLINT     FieldIdentifier,  
     SQLPOINTER      ValuePtr,  
     SQLINTEGER      BufferLength,  
     SQLINTEGER *    StringLengthPtr);

Arguments

DescriptorHandle
[Ввод] Дескрипторная ручка.

RecNumber
[Ввод] Указывает запись дескриптора, из которой приложение ищет информацию. Записи Descriptor нумеруются начиная с 0, при этом запись нумеруется как запись с закладкой. Если аргумент FieldIdentifier указывает на поле заголовка, RecNumber игнорируется. Если RecNumber меньше или равен SQL_DESC_COUNT, но строка не содержит данных для столбца или параметра, вызов SQLGetDescField вернёт значения полей. (Для получения дополнительной информации см. раздел «Инициализация дескрипторных полей» в SQLSetDescField.)

FieldIdentifier
[Ввод] Указывает поле дескриптора, значение которого должно быть возвращено. Для получения дополнительной информации см. раздел «Аргумент идентификатора поля » в SQLSetDescField.

ValuePtr
[Выход] Указатель на буфер для возврата информации о дескрипторе. Тип данных зависит от значения FieldIdentifier.

Если ValuePtr — целый тип, приложения должны использовать буфер SQLULEN и инициализировать значение до 0 перед вызовом этой функции, так как некоторые драйверы могут записывать только нижний 32- или 16-битный буфер и оставлять бит высшего порядка без изменений.

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

BufferLength
[Ввод] Если FieldIdentifier — это поле, определённое ODBC, и ValuePtr указывает на строку символа или бинарный буфер, этот аргумент должен быть длиной *ValuePtr. Если FieldIdentifier — это поле, определённое ODBC, а *ValuePtr — целое число, BufferLength игнорируется. Если значение в *ValuePtr относится к типу данных Unicode (при вызове SQLGetDescFieldW), то аргумент BufferLength должен быть чётным числом.

Если FieldIdentifier — это поле, определяемое драйвером, приложение указывает природу поля Driver Manager, устанавливая аргумент BufferLength . BufferLength может иметь следующие значения:

Если *ValuePtr — указатель на строку символа, то BufferLength — это длина строки или SQL_NTS.
Если *ValuePtr является указателем на двоичный буфер, то приложение размещает результат макроса SQL_LEN_BINARY_ATTR(длина) в BufferLength. Это ставит отрицательное значение в BufferLength.
Если *ValuePtr — это указатель на значение, отличное от строки символа или бинарной строки, то BufferLength должен иметь значение SQL_IS_POINTER.
Если *ValuePtr содержит тип данных фиксированной длины, то BufferLength — это либо SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT или SQL_IS_USMALLINT, в зависимости от необходимости.

StringLengthPtr
[Выход] Указатель на буфер для возврата общего количества байт (без исключения количества байт, необходимых для символа нулевого окончания), доступных для возврата в *ValuePtr.

Returns

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

SQL_NO_DATA возвращается, если RecNumber превышает текущее количество дескрипторных записей.

SQL_NO_DATA возвращается, если DescriptorHandle — это дескриптор IRD, и оператор находится в состоянии подготовленного или выполненного, но открытого курсора с ним не связано.

Diagnostics

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

SQLSTATE	Error	Description
01000	Общее предупреждение	Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
01004	Строковые данные, усеченные справа	Буфер *ValuePtr был недостаточно велик, чтобы вернуть всё дескрипторное поле, поэтому поле было усечено. Длина неусечённого дескрипторного поля возвращается в *StringLengthPtr. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
07009	Индекс некорректного дескриптора	(DM) Аргумент RecNumber был равен 0, атрибут оператора SQL_ATTR_USE_BOOKMARK — SQL_UB_OFF, а аргумент DescriptorHandle был дескриптором IRD. (Эта ошибка может быть возвращена для явно выделенного дескриптора только если дескриптор связан с дескриптором оператора.) Аргумент FieldIdentifier был полем записи, аргумент RecNumber равен 0, а аргумент DescriptorHandle — IPD-дескриптором. Аргумент RecNumber был меньше 0.
08S01	Сбой связи	Связь между драйвером и источником данных, к которому был подключен драйвер, произошел сбой до завершения обработки функции.
HY000	Общая ошибка	Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину.
HY001	Ошибка выделения памяти	Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции.
HY007	Связанная инструкция не подготовлена	DescriptorHandle был связан с StatementHandle как IRD, и связанный оператор не был подготовлен или выполнен.
HY010	Ошибка последовательности функций	(DM) DescriptorHandle был связан с StatementHandle , для которого вызывалась асинхронно выполняющаяся функция (не эта), которая всё ещё выполнялась во время вызова этой функции. (DM) DescriptorHandle был связан с StatementHandle , для которого вызывался и возвращался SQL_NEED_DATA SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos . Эта функция была вызвана до отправки данных для всех параметров выполнения или столбцов. (DM) Для дескриптора соединения, связанного с DescriptorHandle, была вызвана асинхронно выполняющаяся функция. Эта асинхронная функция всё ещё выполнялась, когда была вызвана функция SQLGetDescField .
HY013	Ошибка управления памятью	Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти.
HY021	Несогласованная информация о описаниях	Поля SQL_DESC_TYPE и SQL_DESC_DATETIME_INTERVAL_CODE не образуют действительный тип ODBC SQL, валидный драйвер-специфический тип SQL (для IPD) или допустимый тип ODBC C (для APD или ARD).
HY090	Недопустимая длина строки или буфера	(DM) ValuePtr был строкой символа, а BufferLength* меньше нуля.
HY091	Идентификатор поля некорректного дескриптора	FieldIdentifier не был полем, определённым ODBC, и не был значением, определённым реализацией. Идентификатор поля был неопределен для DescriptorHandle.
HY117	Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения.	(DM) Для получения дополнительной информации о приостановленном состоянии см. Функция SQLEndTran.
HYT01	Время ожидания для подключения истекло	Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Драйвер не поддерживает эту функцию	(DM) Драйвер, связанный с DescriptorHandle , не поддерживает эту функцию.

Comments

Приложение может вызвать SQLGetDescField для возврата значения одного поля записи дескриптора. Вызов SQLGetDescField может вернуть настройки любого поля в любом типе дескриптора, включая поля заголовка, записи и поля закладок. Приложение может получать настройки нескольких полей в одном или разных дескрипторах в произвольном порядке, совершая повторные вызовы SQLGetDescField. SQLGetDescField также может быть вызван для возврата дескрипторных полей, определённых драйвером.

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

Настройки нескольких полей, описывающих имя, тип данных и хранение столбцов или параметров, также можно получить одним вызовом SQLGetDescRec. SQLGetStmtAttr можно вызвать для возврата настройки одного поля в заголовке дескриптора, которое также является атрибутом оператора. SQLColAttribute, SQLDescribeCol и SQLDescribeParam возвращают поля записей или закладок.

Когда приложение вызывает SQLGetDescField для получения значения поля, не определённого для определённого типа дескриптора, функция возвращает SQL_SUCCESS, но возвращаемое значение для поля не определённо. Например, вызов SQLGetDescField для SQL_DESC_NAME или SQL_DESC_NULLABLE поля APD или ARD вернёт SQL_SUCCESS неопределенное значение для этого поля.

Когда приложение вызывает SQLGetDescField для получения значения поля, определённого для определённого типа дескриптора, но не имеющего значения по умолчанию и ещё не установленного, функция возвращает SQL_SUCCESS, но значение для этого поля не определёно. Для получения дополнительной информации о инициализации дескрипторных полей и описаниях полей см. раздел «Инициализация дескрипторных полей» в SQLSetDescField. Дополнительные сведения о дескрипторах см. в разделе "Дескрипторы".

Сведения о	Смотри
Получение нескольких дескрипторных полей	Функция SQLGetDescRec
Задание одного поля дескриптора	Функция SQLSetDescField
Установка нескольких полей дескрипторов	Функция SQLSetDescRec

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-08-24