Функция 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 |