Поделиться через

Функция SQLSetDescRec

  • Статья

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

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

Синтаксис

  
SQLRETURN SQLSetDescRec(  
      SQLHDESC      DescriptorHandle,  
      SQLSMALLINT   RecNumber,  
      SQLSMALLINT   Type,  
      SQLSMALLINT   SubType,  
      SQLLEN        Length,  
      SQLSMALLINT   Precision,  
      SQLSMALLINT   Scale,  
      SQLPOINTER    DataPtr,  
      SQLLEN *      StringLengthPtr,  
      SQLLEN *      IndicatorPtr);

Аргументы

DescriptorHandle
[Входные данные] Дескриптор дескриптор. Это не должен быть дескриптор IRD.

RecNumber
[Входные данные] Указывает запись дескриптора, содержащую заданные поля. Записи дескриптора нумеруются от 0, при этом запись записи 0 является записью закладки. Этот аргумент должен быть равен или больше 0. Если значение recNumber больше значения SQL_DESC_COUNT, SQL_DESC_COUNTis изменено на значение RecNumber.

Тип
[Входные данные] Значение, для которого необходимо задать поле SQL_DESC_TYPE для записи дескриптора.

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

Длина
[Входные данные] Значение, для которого необходимо задать поле SQL_DESC_OCTET_LENGTH для записи дескриптора.

Точность
[Входные данные] Значение, для которого необходимо задать поле SQL_DESC_PRECISION для записи дескриптора.

Масштаб
[Входные данные] Значение, для которого необходимо задать поле SQL_DESC_SCALE для записи дескриптора.

DataPtr
[Отложенные входные или выходные данные] Значение, для которого необходимо задать поле SQL_DESC_DATA_PTR для записи дескриптора. DataPtr можно задать для указателя NULL.

Аргумент DataPtr можно задать для указателя NULL, чтобы задать поле SQL_DESC_DATA_PTR значение null указателя. Если дескриптор в аргументе DescriptorHandle связан с ARD, это отменяет привязку столбца.

StringLengthPtr
[Отложенные входные или выходные данные] Значение, для которого необходимо задать поле SQL_DESC_OCTET_LENGTH_PTR для записи дескриптора. StringLengthPtr можно задать для указателя NULL, чтобы задать для поля SQL_DESC_OCTET_LENGTH_PTR значение null указателя.

ИндикаторPtr
[Отложенные входные или выходные данные] Значение, для которого необходимо задать поле SQL_DESC_INDICATOR_PTR для записи дескриптора. ИндикаторPtr можно задать для указателя NULL, чтобы задать для поля SQL_DESC_INDICATOR_PTR значение null указателя.

Возвраты

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR или SQL_INVALID_HANDLE.

Диагностика

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

SQLSTATE Error Description
01000 Общее предупреждение Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
07009 Недопустимый индекс дескриптора Аргумент RecNumber имеет значение 0, а дескрипторHandle ссылается на дескриптор IPD.

Аргумент RecNumber был меньше 0.

Аргумент RecNumber был больше максимального числа столбцов или параметров, которые может поддерживать источник данных, и аргумент DescriptorHandle был APD, IPD или ARD.

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

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

(DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ДескрипторHandle. Эта анчхронная функция по-прежнему выполнялась при вызове функции SQLSetDescRec .

(DM) SQLExecute, SQLExecDirect или SQLMoreResults был вызван для одного из дескрипторов инструкций, связанных с ДескрипторомHandle и возвращенных SQL_PARAM_DATA_AVAILABLE. Эта функция была вызвана до получения данных для всех потоковых параметров.
HY013 Ошибка управления памятью Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти.
HY016 Не удается изменить дескриптор строки реализации Аргумент DescriptorHandle связан с IRD.
HY021 Несогласованные сведения о дескрипторе Поле "Тип" или любое другое поле, связанное с полем SQL_DESC_TYPE в дескрипторе, не было допустимым или согласованным.

Сведения дескриптора, проверяемые во время проверки согласованности, не согласованы. (См. раздел "Проверки согласованности", далее в этом разделе.)
HY090 Недопустимая длина строки или буфера (DM) Драйвер был драйвером ODBC 2.x , дескриптор был ARD, аргумент ColumnNumber был равен 0, а значение, указанное для аргумента BufferLength , не равно 4.
HY117 Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. (DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function.
HYT01 Время ожидания для подключения истекло Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Драйвер не поддерживает эту функцию (DM) Драйвер, связанный с ДескрипторHandle , не поддерживает функцию.

Комментарии

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

  • SQL_DESC_TYPE

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

  • SQL_DESC_OCTET_LENGTH

  • SQL_DESC_PRECISION

  • SQL_DESC_SCALE

  • SQL_DESC_DATA_PTR

  • SQL_DESC_OCTET_LENGTH_PTR

  • SQL_DESC_INDICATOR_PTR

Заметка

Если вызов SQLSetDescRec завершается ошибкой, содержимое записи дескриптора, определяемой аргументом RecNumber , не определено.

При привязке столбца или параметра SQLSetDescRec позволяет изменять несколько полей, влияющих на привязку, не вызывая SQLBindCol или SQLBindParameter или выполняя несколько вызовов к SQLSetDescField. SQLSetDescRec может задать поля в дескрипторе, не связанном с инструкцией. Обратите внимание, что SQLBindParameter задает больше полей, чем SQLSetDescRec, может задавать поля как в APD, так и IPD в одном вызове и не требует дескриптора.

Заметка

Атрибут инструкции SQL_ATTR_USE_BOOKMARKS всегда должен быть задан перед вызовом SQLSetDescRec с аргументом RecNumber 0, чтобы задать поля закладки. Хотя это не обязательно, настоятельно рекомендуется.

Проверки согласованности

Проверка согласованности выполняется драйвером автоматически, когда приложение устанавливает SQL_DESC_DATA_PTR поле APD, ARD или IPD. Если любое из полей не соответствует другим полям, SQLSetDescRec вернет SQLSTATE HY021 (несогласованные сведения о дескрипторе).

Всякий раз, когда приложение задает SQL_DESC_DATA_PTR поле APD, ARD или IPD, драйвер проверяет, что значение поля SQL_DESC_TYPE и значения, применимые к данному полю SQL_DESC_TYPE, являются допустимыми и согласованными. Эта проверка всегда выполняется при вызове SQLBindParameter или SQLBindCol или при вызове SQLSetDescRec для APD, ARD или IPD. Эта проверка согласованности включает следующие проверки полей дескриптора:

  • Поле SQL_DESC_TYPE должно быть одним из допустимых типов ODBC C или SQL или типа SQL для конкретного драйвера. Поле SQL_DESC_CONCISE_TYPE должно быть одним из допустимых типов ODBC C или SQL или типа драйвера C или SQL, включая краткие типы даты и интервалов.

  • Если поле записи SQL_DESC_TYPE SQL_DATETIME или SQL_INTERVAL, поле SQL_DESC_DATETIME_INTERVAL_CODE должно быть одним из допустимых кодов даты или интервала. (См. описание поля SQL_DESC_DATETIME_INTERVAL_CODE в SQLSetDescField.)

  • Если поле SQL_DESC_TYPE указывает числовой тип, SQL_DESC_PRECISION и SQL_DESC_SCALE поля проверяются как допустимые.

  • Если поле SQL_DESC_CONCISE_TYPE является типом данных time или timestamp, тип интервала с компонентом секунд или одним из типов данных интервала с компонентом времени, то поле SQL_DESC_PRECISION проверяется, что это допустимая точность секунд.

  • Если SQL_DESC_CONCISE_TYPE является типом данных интервала, поле SQL_DESC_DATETIME_INTERVAL_PRECISION проверяется как допустимое значение максимальной точности интервала.

Поле SQL_DESC_DATA_PTR IPD обычно не задано; однако приложение может сделать это, чтобы принудительно проверить согласованность полей IPD. Проверка согласованности не может выполняться в IRD. Значение, для которого задано поле SQL_DESC_DATA_PTR IPD, не сохраняется и не может быть извлечено вызовом SQLGetDescField или SQLGetDescRec; параметр выполняется только для принудительной проверки согласованности.

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

См. также

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