Функция SQLGetEnvAttr

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

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

Синтаксис

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

Аргументы

EnvironmentHandle
[Входные данные] Дескриптор среды.

Атрибут
[Входные данные] Атрибут для получения.

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

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

BufferLength
[Входные данные] Если ЗначениеPtr указывает на строку символов, этот аргумент должен быть длиной *ValuePtr. Если значение *ValuePtr является целым числом, буферLength игнорируется. Если *ValuePtr является строкой Юникода (при вызове SQLGetEnvAttrW), аргумент BufferLength должен быть четным. Если значение атрибута не является строкой символов, bufferLength не используется.

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

Возвраты

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

Диагностика

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

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

Комментарии

Список атрибутов см. в разделе SQLSetEnvAttr. Атрибуты среды для конкретного драйвера отсутствуют. Если атрибут указывает атрибут, возвращающий строку, ЗначениеPtr должно быть указателем на буфер, в котором возвращается строка. Максимальная длина строки, включая байт завершения NULL, будет байт 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

См. также

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