Функция SQLGetStmtAttr

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

Сводка
SQLGetStmtAttr возвращает текущую настройку атрибута оператора.

Замечание

Для получения дополнительной информации о том, на что Driver Manager отображает эту функцию при ODBC 3. x приложение работает с ODBC 2. драйвер x , см. функции замены отображения для обратной совместимости приложений.

Syntax

  
SQLRETURN SQLGetStmtAttr(  
     SQLHSTMT        StatementHandle,  
     SQLINTEGER      Attribute,  
     SQLPOINTER      ValuePtr,  
     SQLINTEGER      BufferLength,  
     SQLINTEGER *    StringLengthPtr);

Arguments

ОператорHandle
[Входные данные] Дескриптор инструкции.

Атрибут
[Ввод] Атрибут для поиска.

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

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

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

Если Attribute — это атрибут, определяемый драйвером, приложение указывает природу атрибута Driver Manager, устанавливая аргумент BufferLength . BufferLength может иметь следующие значения:

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

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

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

  • Если *ValuePtr содержит тип данных фиксированной длины, то BufferLength — это либо SQL_IS_INTEGER, либо SQL_IS_UINTEGER, в зависимости от необходимости.

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

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR или SQL_INVALID_HANDLE.

Diagnostics

Когда SQLGetStmtAttr возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить, вызвав SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и HandleHandleStatementHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращает SQLGetStmtAttr , и каждое из них объясняется в контексте этой функции; обозначение «(DM)» предшествует описаниям SQLSTATE, возвращаемым менеджером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.

SQLSTATE Error Description
01000 Общее предупреждение Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
01004 Строковые данные, усеченные справа Данные, возвращаемые в *ValuePtr , были усечены до BufferLength минус длина символа нулевой терминации. Длина неусечённого значения строки возвращается в *StringLengthPtr. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
24000 Недопустимое состояние курсора Аргумент Attribute был SQL_ATTR_ROW_NUMBER и курсор не был открыт, или курсор располагался до начала набора результатов или после окончания результата.
HY000 Общая ошибка Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в аргументе MessageText , описывает ошибку и её причину.
HY001 Ошибка выделения памяти Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции.
HY010 Ошибка последовательности функций (DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ОператоромHandle. Эта асинхронная функция всё ещё выполнялась, когда была вызвана функция SQLGetStmtAttr .

(DM) асинхронно выполняющаяся функция была вызвана для StatementHandle и по-прежнему выполнялась при вызове этой функции.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos были вызваны для ОператораHandle и возвращены SQL_NEED_DATA. Эта функция была вызвана до отправки данных для всех параметров выполнения или столбцов.
HY013 Ошибка управления памятью Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти.
HY090 Недопустимая длина строки или буфера (DM) *ValuePtr — это строка символа, а BufferLength был меньше нуля, но не равен SQL_NTS.
HY092 Некорректный идентификатор атрибута/опции Значение, указанное для аргумента Attribute , не было действительным для версии ODBC, поддерживаемой драйвером.
HY109 Недопустимое положение курсора Аргумент Атрибута был SQL_ATTR_ROW_NUMBER, и строка была удалена или не могла быть извлечена.
HY117 Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. (DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function.
HYC00 Необязательный компонент не реализован Значение, указанное для аргумента Attribute , было действительным атрибутом оператора ODBC для версии ODBC, поддерживаемой драйвером, но не поддерживалось самим драйвером.
HYT01 Время ожидания для подключения истекло Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Драйвер не поддерживает эту функцию (DM) Драйвер, соответствующий ОператорHandle , не поддерживает функцию.

Comments

Для общей информации об атрибутах утверждений см. раздел Атрибуты утверждений.

Вызов SQLGetStmtAttr возвращает в *ValuePtr значение атрибута оператора, указанного в Атрибуте. Это значение может быть либо значением SQLULEN, либо строкой символа с нулевой терминацией. Если значение является значением SQLULEN, некоторые драйверы могут записывать только нижний 32- или 16-битный буфер и оставлять бит высшего порядка без изменений. Поэтому приложения должны использовать буфер SQLULEN и инициализировать значение в 0 перед вызовом этой функции. Также аргументы BufferLength и StringLengthPtr не используются. Если значение — строка с null-termination, приложение указывает максимальную длину этой строки в аргументе BufferLength , и драйвер возвращает длину этой строки в буфере *StringLengthPtr .

Чтобы позволить приложениям, вызывающим SQLGetStmtAttr , работать с ODBC 2. x драйверов, вызов SQLGetStmtAttr отображается в Driver Manager в SQLGetStmtOption.

Следующие атрибуты операторов являются только для чтения, поэтому их можно получить с помощью SQLGetStmtAttr, но не устанавливать SQLSetStmtAttr:

  • SQL_ATTR_IMP_PARAM_DESC

  • SQL_ATTR_IMP_ROW_DESC

  • SQL_ATTR_ROW_NUMBER

Для списка атрибутов, которые можно задать и извлечь, см. SQLSetStmtAttr.

Сведения о Смотри
Возврат параметра атрибута подключения Функция SQLGetConnectAttr
Установка атрибута соединения Функция SQLSetConnectAttr
Задание атрибута инструкции Функция SQLSetStmtAttr

Связанные материалы

  • Last updated on