Функция 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 |
См. также
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по