Функция SQLGetEnvAttr

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

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

Syntax

  
SQLRETURN SQLGetEnvAttr(  
     SQLHENV        EnvironmentHandle,  
     SQLINTEGER     Attribute,  
     SQLPOINTER     ValuePtr,  
     SQLINTEGER     BufferLength,  
     SQLINTEGER *   StringLengthPtr);

Arguments

EnvironmentHandle
[Ввод] Управление окружением.

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

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

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

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

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

Returns

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

Diagnostics

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

SQLSTATE Error Description
01000 Общее предупреждение Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
01004 Строковые данные, усеченные справа Данные, возвращаемые в *ValuePtr , были усечены до BufferLength минус символ нулевой терминации. Длина неусечённого значения строки возвращается в *StringLengthPtr. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
HY000 Общая ошибка Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину.
HY001 Ошибка выделения памяти Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции.
HY010 Ошибка последовательности функций (DM) SQL_ATTR_ODBC_VERSION ещё не зададено через SQLSetEnvAttr. Не обязательно устанавливать SQL_ATTR_ODBC_VERSION явно, если вы используете SQLAllocHandleStd.
HY013 Ошибка управления памятью Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти.
HY092 Некорректный идентификатор атрибута/опции Значение, указанное для аргумента Attribute , не было действительным для версии ODBC, поддерживаемой драйвером.
HY117 Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. (DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function.
HYC00 Необязательный компонент не реализован Значение, указанное для аргумента Attribute , было действительным атрибутом среды ODBC для версии ODBC, поддерживаемой драйвером, но не поддерживалось самим драйвером.
IM001 Драйвер не поддерживает эту функцию (DM) Драйвер, соответствующий EnvironmentHandle , не поддерживает эту функцию.

Comments

Список атрибутов см. SQLSetEnvAttr. Нет специфических атрибутов окружения, специфичных для водителя. Если Attribute указывает атрибут, возвращающий строку, ValuePtr должен быть указателем на буфер, в котором возвращается строка. Максимальная длина строки, включая байт нулевого окончания, будет BufferLength .

SQLGetEnvAttr может быть вызван в любой момент между выделением и освобождением дескриптора среды. Все атрибуты среды, успешно заданные приложением для среды, сохраняются до тех пор, пока SQLFreeHandle не будет вызван на EnvironmentHandle с HandleType SQL_HANDLE_ENV. В ODBC 3*.x* одновременно может быть выделено несколько дескрипторов среды. Атрибут окружающей среды в одной среде не затрагивается, когда была выделена другая среда.

Замечание

Атрибут SQL_ATTR_OUTPUT_NTS среды поддерживается приложениями, соответствующими стандартам. Когда вызывается SQLGetEnvAttr , менеджер драйверов ODBC 3*.x* всегда возвращает SQL_TRUE для этого атрибута. SQL_ATTR_OUTPUT_NTS можно настроить в SQL_TRUE только вызовом SQLSetEnvAttr.

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

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

  • Last updated on