Бөлісу құралы:

Функция SQLGetDescRec

  • Мақала

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

Сводка
SQLGetDescRec возвращает текущие параметры или значения нескольких полей записи дескриптора. Возвращаемые поля описывают имя, тип данных и хранилище данных столбцов или параметров.

Синтаксис

  
SQLRETURN SQLGetDescRec(  
      SQLHDESC        DescriptorHandle,  
      SQLSMALLINT     RecNumber,  
      SQLCHAR *       Name,  
      SQLSMALLINT     BufferLength,  
      SQLSMALLINT *   StringLengthPtr,  
      SQLSMALLINT *   TypePtr,  
      SQLSMALLINT *   SubTypePtr,  
      SQLLEN *        LengthPtr,  
      SQLSMALLINT *   PrecisionPtr,  
      SQLSMALLINT *   ScalePtr,  
      SQLSMALLINT *   NullablePtr);

Аргументы

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

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

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

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

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

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

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

SubTypePtr
[Выходные данные] Для записей, тип которых SQL_DATETIME или SQL_INTERVAL, это указатель на буфер, в котором возвращается значение поля SQL_DESC_DATETIME_INTERVAL_CODE.

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

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

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

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

Возвраты

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

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

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

Диагностика

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

SQLSTATE Error Description
01000 Общее предупреждение Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
01004 Строковые данные, усеченные справа Буфер *Имя было недостаточно большим, чтобы вернуть все поле дескриптора. Поэтому поле усечено. Длина ненадежного поля дескриптора возвращается в *StringLengthPtr. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
07009 Недопустимый индекс дескриптора Аргумент FieldIdentifier был полем записи, аргумент RecNumber был задан в значение 0, а аргумент DescriptorHandle был дескриптором IPD.

(DM) Аргумент RecNumber был задан в значение 0, а атрибут инструкции SQL_ATTR_USE_BOOKMARKS был задан как SQL_UB_OFF, а аргумент DescriptorHandle — дескриптор IRD.

Аргумент RecNumber был меньше 0.
08S01 Сбой связи Связь между драйвером и источником данных, к которому был подключен драйвер, произошел сбой до завершения обработки функции.
HY000 Общая ошибка Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину.
HY001 Ошибка выделения памяти Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции.
HY007 Связанная инструкция не подготовлена ДескрипторHandle связан с IRD, а связанный дескриптор инструкции не был в подготовленном или исполняемом состоянии.
HY010 Ошибка последовательности функций Дескриптор Dm) Был связан с оператором StatementHandle, для которого была вызвана асинхронная функция (не эта) и все еще выполнялась при вызове этой функции.

(DM) DescriptorHandle был связан с операторомHandle, для которого SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos был вызван и возвращен SQL_NEED_DATA. Эта функция была вызвана до отправки данных для всех параметров выполнения или столбцов.

(DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ДескрипторHandle. Эта асинхронная функция по-прежнему выполнялась при вызове SQLGetDescRec .
HY013 Ошибка управления памятью Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти.
HY117 Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. (DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function.
HYT01 Время ожидания для подключения истекло Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Драйвер не поддерживает эту функцию (DM) Драйвер, связанный с ДескрипторHandle , не поддерживает функцию.

Комментарии

Приложение может вызвать SQLGetDescRec , чтобы получить значения следующих полей дескриптора для одного столбца или параметра:

  • SQL_DESC_NAME

  • SQL_DESC_TYPE

  • SQL_DESC_DATETIME_INTERVAL_CODE (для записей, тип которых SQL_DATETIME или SQL_INTERVAL)

  • SQL_DESC_OCTET_LENGTH

  • SQL_DESC_PRECISION

  • SQL_DESC_SCALE

  • SQL_DESC_NULLABLE

SQLGetDescRec не получает значения для полей заголовка.

Приложение может предотвратить возвращение параметра поля, задав аргумент, соответствующий полю null-указателю.

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

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

Значения полей также можно получить по отдельности путем вызова SQLGetDescField. Описание полей в заголовке дескриптора или записи см. в разделе SQLSetDescField. Дополнительные сведения о дескрипторах см. в разделе "Дескрипторы".

Сведения Раздел
Привязка столбца Функция SQLBindCol
Привязка параметра Функция SQLBindParameter
Получение поля дескриптора Функция SQLGetDescField
Настройка нескольких полей дескриптора Функция SQLSetDescRec

См. также

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