Функция SQLGetDescField

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

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

Синтаксис

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

Аргументы

DescriptorHandle
[Входные данные] Дескриптор дескриптор.

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

FieldIdentifier
[Входные данные] Указывает поле дескриптора, значение которого необходимо вернуть. Дополнительные сведения см. в разделе "Аргумент FieldIdentifier " в SQLSetDescField.

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

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

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

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

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

• Если *ValuePtr является указателем на символьную строку, буферLength — это длина строки или SQL_NTS.

• Если *ValuePtr является указателем на двоичный буфер, приложение помещает результат макроса SQL_LEN_BINARY_ATTR(длина) в BufferLength. Это помещает отрицательное значение в BufferLength.

• Если *ValuePtr является указателем на значение, отличное от символьной строки или двоичной строки, буферLength должен иметь значение SQL_IS_POINTER.

• Если параметр *ValuePtr содержит тип данных фиксированной длины, буферLength имеет значение SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT или SQL_IS_USMALLINT.

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

Возвраты

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

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

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

Диагностика

Когда SQLGetDescField возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить путем вызова SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и handle of StatementHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLGetDescField и описываются в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением 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	Связанная инструкция не подготовлена	ДескрипторHandle был связан с оператором StatementHandle как IRD, и связанный дескриптор инструкции не был подготовлен или выполнен.
HY010	Ошибка последовательности функций	Дескриптор Dm) Был связан с оператором StatementHandle, для которого была вызвана асинхронная функция (не эта) и все еще выполнялась при вызове этой функции. (DM) DescriptorHandle был связан с операторомHandle, для которого SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos был вызван и возвращен SQL_NEED_DATA. Эта функция была вызвана до отправки данных для всех параметров выполнения или столбцов. (DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ДескрипторHandle. Эта асинхронная функция по-прежнему выполнялась при вызове функции SQLGetDescField .
HY013	Ошибка управления памятью	Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти.
HY021	Несогласованные сведения о дескрипторе	Поля SQL_DESC_TYPE и SQL_DESC_DATETIME_INTERVAL_CODE не образуют допустимый тип SQL ODBC, допустимый тип SQL для конкретного драйвера (для IPD) или допустимый тип ODBC C (для APD или ARD).
HY090	Недопустимая длина строки или буфера	(DM) *ValuePtr была символьной строкой, и BufferLength было меньше нуля.
HY091	Недопустимый идентификатор поля дескриптора	FieldIdentifier не является полем, определяемым ODBC, и не является определяемым реализацией значением. FieldIdentifier не определен для ДескриптораHandle.
HY117	Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения.	(DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function.
HYT01	Время ожидания для подключения истекло	Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Драйвер не поддерживает эту функцию	(DM) Драйвер, связанный с ДескрипторHandle , не поддерживает функцию.

Комментарии

Приложение может вызвать 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

См. также

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