Функция 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 |