Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Соответствие
Введенная версия: Соответствие стандартам ODBC 3.0: ISO 92
Сводка
SQLSetEnvAttr задаёт атрибуты, управляющие аспектами среды.
Syntax
SQLRETURN SQLSetEnvAttr(
SQLHENV EnvironmentHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER StringLength);
Arguments
EnvironmentHandle
[Ввод] Управление окружением.
Атрибут
[Ввод] Атрибут к набору, указанный в разделе «Комментарии».
ValuePtr
[Ввод] Указатель на значение, которое должно быть связано с атрибутом. В зависимости от значения Attribute, ValuePtr будет 32-битным целочисленным значением или указывает на строку символа с нулевой концовкой.
StringLength
[Ввод] Если ValuePtr указывает на строку символа или бинарный буфер, этот аргумент должен быть длиной *ValuePtr. Для данных строк символов этот аргумент должен содержать количество байт в строке.
Если ValuePtr — целое число, StringLength игнорируется.
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR или SQL_INVALID_HANDLE.
Diagnostics
Когда SQLSetEnvAttr возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить, вызвав SQLGetDiagRec с помощью HandleType SQL_HANDLE_ENV и HandleHandleEnvironmentHandle. В следующей таблице перечислены значения SQLSTATE, обычно возвращаемые SQLSetEnvAttr , и каждое из них объясняется в контексте этой функции; обозначение «(DM)» предшествует описаниям SQLSTATE, возвращаемым менеджером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное. Если драйвер не поддерживает атрибут среды, ошибка может быть возвращена только во время подключения.
| SQLSTATE | Error | Description |
|---|---|---|
| 01000 | Общее предупреждение | Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 01S02 | Изменено значение параметра | Драйвер не поддерживал значение, указанное в ValuePtr , и заменял его аналогичным значением. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| HY000 | Общая ошибка | Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину. |
| HY001 | Ошибка выделения памяти | Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции. |
| HY009 | Недопустимое использование указателя NULL | Аргумент Attribute определял атрибут среды, требующий строкового значения, а аргумент ValuePtr был null-указателем. |
| HY010 | Ошибка последовательности функций | (DM) В EnvironmentHandle выделен дескриптор соединения. (DM) SQL_ATTR_ODBC_VERSION не был установлен с помощью SQLSetEnvAttr , и Атрибут не равен SQL_ATTR_ODBC_VERSION. Не обязательно устанавливать SQL_ATTR_ODBC_VERSION явно, если вы используете SQLAllocHandleStd. |
| HY013 | Ошибка управления памятью | Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти. |
| HY024 | Недопустимое значение атрибута | Учитывая указанное значение атрибута , недопустимое значение было указано в ValuePtr. |
| HY090 | Недопустимая длина строки или буфера | Аргумент StringLength был меньше 0, но не был SQL_NTS. |
| HY092 | Некорректный идентификатор атрибута/опции | (DM) Значение, указанное для атрибута аргумента, недопустимо для версии ODBC, поддерживаемой драйвером. |
| HY117 | Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. | (DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function. |
| HYC00 | Необязательный компонент не реализован | Значение, указанное для аргумента Attribute , было действительным атрибутом среды ODBC для поддерживаемой драйвером версии ODBC, но не поддерживалось драйвером. (DM) Аргумент об атрибуте был SQL_ATTR_OUTPUT_NTS, а ValuePtr — SQL_FALSE. |
Comments
Приложение может вызывать SQLSetEnvAttr только если в среде не выделен дескриптор соединения. Все атрибуты среды, успешно заданные приложением для среды, сохраняются до вызова SQLFreeHandle в этой среде. В ODBC 3.x можно одновременно выделить несколько дескрипторов среды.
Формат информации, заданной через ValuePtr , зависит от указанного атрибута. SQLSetEnvAttr принимает информацию об атрибутах в одном из двух форматов: строка символа с нулевой концовкой или 32-битное целочисленное значение. Формат каждого из них указывается в описании атрибута.
Нет специфических атрибутов окружения, специфичных для водителя.
Атрибуты соединения не могут быть зададены вызовом SQLSetEnvAttr. Попытка сделать это вернёт SQLSTATE HY092 (Invalid attribute/option identifier).
| Атрибут | Содержимое ValuePtr |
|---|---|
| SQL_ATTR_CONNECTION_POOLING (ODBC 3.8) | 32-битное значение SQLUINTEGER, которое позволяет или отключает пул соединений на уровне среды. Используются следующие значения: SQL_CP_OFF = Пулирование соединений отключено. Это значение по умолчанию. SQL_CP_ONE_PER_DRIVER = Поддерживается один пул соединений для каждого драйвера. Каждое соединение в пуле связано с одним драйвером. SQL_CP_ONE_PER_HENV = Поддерживается один пул соединений для каждой среды. Каждое соединение в пуле связано с одной средой. SQL_CP_DRIVER_AWARE = Используйте функцию осведомлённости пула соединений драйвера, если она доступна. Если драйвер не поддерживает осведомленность о пуле соединений, SQL_CP_DRIVER_AWARE игнорируется и используется SQL_CP_ONE_PER_HENV. Дополнительные сведения см. в разделе Пул подключений с учетом драйвера. В среде, где некоторые драйверы поддерживают, а некоторые — нет, осведомлённость о пуле соединений, SQL_CP_DRIVER_AWARE может включить функцию осведомлённости о пуле соединений для поддерживающих драйверов, но это эквивалентно установке SQL_CP_ONE_PER_HENV на тех драйверах, которые не поддерживают функцию осведомлённости о пуле соединений. Пул соединений активируется вызовом SQLSetEnvAttr для установки атрибута SQL_ATTR_CONNECTION_POOLING в SQL_CP_ONE_PER_DRIVER или SQL_CP_ONE_PER_HENV. Этот вызов необходимо выполнить, прежде чем приложение выделяет общую среду, для которой необходимо включить пул подключений. Дескриптор среды в вызове SQLSetEnvAttr установлен как null, что делает SQL_ATTR_CONNECTION_POOLING атрибутом на уровне процесса. После включения пула соединений приложение выделяет неявную общую среду, вызывая SQLAllocHandle с аргументом InputHandle в SQL_HANDLE_ENV. После включения пула соединений и выбора общей среды для приложения SQL_ATTR_CONNECTION_POOLING нельзя сбросить для этой среды, поскольку SQLSetEnvAttr вызывается с помощью дескриптора null среды при установке этого атрибута. Если этот атрибут установлен, когда пул соединений уже включен в общей среде, атрибут затрагивает только те общие среды, которые выделяются впоследствии. Также возможно включить пул соединений в определённой среде. Обратите внимание на следующее о пуле соединений среди окружения: - Включение пула соединений на дескрипте NULL является атрибутом на уровне процесса. Впоследствии выделенные среды будут общими и унаследуют параметры пула соединений на уровне процесса. - После выделения среды приложение всё ещё может изменить настройки пула соединений. - Если пул соединений среды включён, а драйвер соединения использует пул драйверов, предпочтение отдаёт пул среды. SQL_ATTR_CONNECTION_POOLING реализовано внутри Driver Manager. Драйверу не нужно внедрять SQL_ATTR_CONNECTION_POOLING. Приложения ODBC 2.0 и 3.0 могут устанавливать этот атрибут среды. Дополнительные сведения см. в статье Организация пулов соединений ODBC. |
| SQL_ATTR_CP_MATCH (ODBC 3.0) | 32-битное значение SQLUINTEGER, определяющее, как выбирается соединение из пула соединений. Когда вызывается SQLConnect или SQLDriverConnect , менеджер драйверов определяет, какое соединение будет повторно использовано из пула. Менеджер драйверов пытается сопоставить параметры соединения в вызове и атрибуты соединения, установленные приложением, с ключевыми словами и атрибутами соединений соединений в пуле. Значение этого атрибута определяет уровень точности критериев сопоставления. Для установления значения этого атрибута используются следующие значения: SQL_CP_STRICT_MATCH = Повторно используются только соединения, которые точно совпадают с опциями соединения в вызове и атрибутами соединения, заданными приложением. Это значение по умолчанию. SQL_CP_RELAXED_MATCH = Могут использоваться связи с соответствующими строка подключения ключевыми словами. Ключевые слова должны совпадать, но не все атрибуты соединения должны совпадать. Для получения дополнительной информации о том, как менеджер драйверов выполняет совпадение при подключении к пуловому соединению, см. SQLConnect. Дополнительные сведения о пуле подключений см. в разделе "Пул подключений ODBC". |
| SQL_ATTR_ODBC_VERSION (ODBC 3.0) | 32-битное целое число, определяющее, проявляет ли определённая функциональность поведение ODBC 2.x или ODBC 3.x . Для установления значения этого атрибута используются следующие значения: SQL_OV_ODBC3_80 = Менеджер водителей и водитель проявляют следующее поведение по ODBC 3.8: - Драйвер возвращает и ожидает коды ODBC 3.x для даты, времени и временной метки. - Драйвер возвращает коды ODBC 3.x SQLSTATE при вызове SQLError, SQLGetDiagField или SQLGetDiagRec . - Аргумент CatalogName в вызове SQLTables принимает шаблон поиска. - Менеджер драйверов поддерживает расширяемость типа данных C. Для получения дополнительной информации о расширяемости типов данных C см. Типы данных C в ODBC. Для получения дополнительной информации смотрите в разделе «Что нового в ODBC 3.8». SQL_OV_ODBC3 = Менеджер драйверов и водитель проявляют следующее поведение ODBC 3.x : - Драйвер возвращает и ожидает коды ODBC 3.x для даты, времени и временной метки. - Драйвер возвращает коды ODBC 3.x SQLSTATE при вызове SQLError, SQLGetDiagField или SQLGetDiagRec . - Аргумент CatalogName в вызове SQLTables принимает шаблон поиска. - Менеджер драйверов не поддерживает расширяемость типов данных C. SQL_OV_ODBC2 = Менеджер водителей и водитель проявляют следующее поведение ODBC 2.x . Это особенно полезно для приложений ODBC 2.x , работающего с драйвером ODBC 3.x . - Драйвер возвращает и ожидает коды ODBC 2.x для даты, времени и временной метки. - Драйвер возвращает коды ODBC 2.x SQLSTATE при вызове SQLError, SQLGetDiagField или SQLGetDiagRec . - Аргумент CatalogName в вызове SQLTables не принимает шаблон поиска. - Менеджер драйверов не поддерживает расширяемость типов данных C. Приложение должно задать этот атрибут среды перед вызовом любой функции с аргументом SQLHENV, иначе вызов вернёт SQLSTATE HY010 (ошибка последовательности функций). Зависит от водителя, существует ли дополнительное поведение для этих экологических флагов. - Для получения дополнительной информации см. разделы «Объявление ODBC версии приложения и поведенческие изменения». |
| SQL_ATTR_OUTPUT_NTS (ODBC 3.0) | 32-битное целое число, определяющее, как драйвер возвращает строковые данные. Если SQL_TRUE, драйвер возвращает данные строк с нулевой терминацией. Если SQL_FALSE, драйвер не возвращает данные строк с нулевой терминацией. Этот атрибут по умолчанию относится к SQL_TRUE. Вызов SQLSetEnvAttr для установки SQL_TRUE возвращает SQL_SUCCESS. Вызов SQLSetEnvAttr для установки SQL_FALSE возвращает SQL_ERROR и SQLSTATE HYC00 (опциональная функция не реализована). |
Связанные функции
| Сведения о | Смотри |
|---|---|
| Выделение ручки | Функция SQLAllocHandle |
| Возврат настройки атрибута окружающей среды | Функция SQLGetEnvAttr |