Функция SQLSetEnvAttr

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

Сводка
SQLSetEnvAttr задает атрибуты, управляющие аспектами сред.

Синтаксис

  
SQLRETURN SQLSetEnvAttr(  
     SQLHENV      EnvironmentHandle,  
     SQLINTEGER   Attribute,  
     SQLPOINTER   ValuePtr,  
     SQLINTEGER   StringLength);  

Аргументы

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

Атрибут
[Входные данные] Атрибут для задания, указанный в разделе "Комментарии".

ValuePtr
[Входные данные] Указатель на значение, связанное с атрибутом. В зависимости от значения Атрибута значение ValuePtr будет 32-разрядным целым числом или указывает на строку символов, завершаемую значением NULL.

StringLength
[Входные данные] Если ЗначениеPtr указывает на символьную строку или двоичный буфер, этот аргумент должен быть длиной *ValuePtr. Для символьных строковых данных этот аргумент должен содержать количество байтов в строке.

Если ValuePtr является целым числом, StringLength игнорируется.

Возвраты

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR или SQL_INVALID_HANDLE.

Диагностика

Когда SQLSetEnvAttr возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить путем вызова SQLGetDiagRec с помощью HandleType SQL_HANDLE_ENV и Handle of EnvironmentHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLSetEnvAttr и объясняются в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением 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	Аргумент Атрибута определил атрибут среды, который требовал строковое значение, и аргумент ValuePtr был пустым указателем.
HY010	Ошибка последовательности функций	(DM) Дескриптор подключения выделен в EnvironmentHandle. (DM) SQL_ATTR_ODBC_VERSION не заданы с помощью SQLSetEnvAttr и атрибут не равен SQL_ATTR_ODBC_VERSION. Если вы используете SQLAllocHandleStd, вам не нужно явно задавать SQL_ATTR_ODBC_VERSION.
HY013	Ошибка управления памятью	Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти.
HY024	Недопустимое значение атрибута	Учитывая указанное значение атрибута , недопустимое значение было указано в ValuePtr.
HY090	Недопустимая длина строки или буфера	Аргумент StringLength был меньше 0, но не был SQL_NTS.
HY092	Недопустимый идентификатор атрибута или параметра	(DM) Значение, указанное для атрибута аргумента, недопустимо для версии ODBC, поддерживаемой драйвером.
HY117	Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения.	(DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function.
HYC00	Необязательный компонент не реализован	Значение, указанное для атрибута аргумента, является допустимым атрибутом среды ODBC для версии ODBC, поддерживаемой драйвером, но не поддерживается драйвером. (DM) Аргумент атрибута был SQL_ATTR_OUTPUT_NTS, и ЗначениеPtr было SQL_FALSE.

Комментарии

Приложение может вызывать SQLSetEnvAttr только в том случае, если в среде не выделен дескриптор подключения. Все атрибуты среды, успешно заданные приложением для среды, сохраняются до вызова SQLFreeHandle в среде. Несколько дескрипторов среды можно выделить одновременно в ODBC 3.x.

Формат информации, заданный с помощью ValuePtr , зависит от указанного атрибута. SQLSetEnvAttr принимает сведения о атрибутах в одном из двух разных форматов: строке символов, завершаемой null, или 32-разрядном целочисленном значении. Формат каждого из них указывается в описании атрибута.

Атрибуты среды для конкретного драйвера отсутствуют.

Атрибуты подключения нельзя задать вызовом SQLSetEnvAttr. При попытке этого будет возвращен идентификатор SQLSTATE HY092 (недопустимый атрибут или идентификатор параметра).

Атрибут	Содержимое 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 реализуется в диспетчере драйверов. Драйвер не должен реализовывать 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, драйвер возвращает строковые данные, завершаемые значением NULL. Если SQL_FALSE, драйвер не возвращает строковые данные, завершаемые значением NULL. Этот атрибут по умолчанию используется для SQL_TRUE. Вызов SQLSetEnvAttr , чтобы задать для него значение SQL_TRUE возвращает SQL_SUCCESS. Вызов SQLSetEnvAttr , чтобы задать для него значение SQL_FALSE возвращает SQL_ERROR и HYC00 SQLSTATE (необязательная функция не реализована).

Связанные функции

Сведения	Раздел
Выделение дескриптора	Функция SQLAllocHandle
Возврат параметра атрибута среды	Функция SQLGetEnvAttr

См. также

Справочник по API ODBC
Файлы заголовков ODBC
Новые возможности ODBC 3.8