Функция SQLGetConnectAttr

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

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

Замечание

Для получения дополнительной информации о том, на что Driver Manager отображает эту функцию, когда приложение ODBC 3*.x* работает с драйвером ODBC 2*.x*, см. раздел Функции замены отображения для обратной совместимости приложений.

Syntax

  
SQLRETURN SQLGetConnectAttr(  
     SQLHDBC        ConnectionHandle,  
     SQLINTEGER     Attribute,  
     SQLPOINTER     ValuePtr,  
     SQLINTEGER     BufferLength,  
     SQLINTEGER *   StringLengthPtr);

Arguments

ConnectionHandle
[Input] Дескриптор подключения

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

ValuePtr
[Выход] Указатель в память для возврата текущего значения атрибута, заданного атрибутом. Для атрибутов целого числа некоторые драйверы могут записывать только нижний 32- или 16-битный буфер и оставлять бит высшего порядка без изменений. Поэтому приложения должны использовать буфер SQLULEN и инициализировать значение в 0 перед вызовом этой функции.

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

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

Если Attribute — это атрибут, определяемый драйвером, приложение указывает природу атрибута Driver Manager, устанавливая аргумент BufferLength . BufferLength может иметь следующие значения:

Если *ValuePtr — указатель на строку символа, то BufferLength — длина строки.
Если *ValuePtr является указателем на бинарный буфер, приложение помещает результат макроса SQL_LEN_BINARY_ATTR(длина) в BufferLength. Это ставит отрицательное значение в BufferLength.
Если *ValuePtr — это указатель на значение, отличное от строки символа или бинарной строки, BufferLength должен иметь значение SQL_IS_POINTER.
Если *ValuePtr содержит тип данных фиксированной длины, BufferLength — это либо SQL_IS_INTEGER, либо SQL_IS_UINTEGER, в зависимости от необходимости.

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

Returns

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

Diagnostics

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

SQLSTATE	Error	Description
01000	Общее предупреждение	Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
01004	Строковые данные, усеченные справа	Данные, возвращаемые в *ValuePtr , были усечены до BufferLength минус длина символа нулевой терминации. Длина неусечённого значения строки возвращается в *StringLengthPtr. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
08003	Подключение не открыто	(DM) Было указано значение Attribute , требующее открытого соединения.
08S01	Сбой связи	Связь между драйвером и источником данных, к которому был подключен драйвер, произошел сбой до завершения обработки функции.
HY000	Общая ошибка	Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое из диагностической структуры через аргумент MessageText в SQLGetDiagField , описывает ошибку и её причину.
HY001	Ошибка выделения памяти	Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции.
HY010	Ошибка последовательности функций	(DM) SQLBrowseConnect был вызван для ConnectionHandle и вернул SQL_NEED_DATA. Эта функция вызывалась до того, как SQLBrowseConnect возвращал SQL_SUCCESS_WITH_INFO или SQL_SUCCESS. (DM) SQLExecute, SQLExecDirect или SQLMoreResults был вызван для ConnectionHandle и вернут SQL_PARAM_DATA_AVAILABLE. Эта функция была вызвана до получения данных для всех потоковых параметров.
HY013	Ошибка управления памятью	Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти.
HY090	Недопустимая длина строки или буфера	(DM) *ValuePtr — это строка символа, а BufferLength был меньше нуля, но не равен SQL_NTS.
HY092	Некорректный идентификатор атрибута/опции	Значение, указанное для аргумента Attribute , не было действительным для версии ODBC, поддерживаемой драйвером.
HY114	Драйвер не поддерживает асинхронное выполнение функций на уровне соединения	(DM) Приложение попыталось включить асинхронное выполнение функций с помощью SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE для драйвера, не поддерживающего операции асинхронного соединения.
HY117	Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения.	(DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function.
HYC00	Необязательный компонент не реализован	Значение, указанное для аргумента Attribute , было действительным атрибутом соединения ODBC для версии ODBC, поддерживаемой драйвером, но не поддерживалось драйвером.
HYT01	Время ожидания для подключения истекло	Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Драйвер не поддерживает эту функцию	(DM) Драйвер, соответствующий ConnectionHandle , не поддерживает функцию.

Comments

Для общей информации об атрибутах соединения см. раздел «Атрибуты связи».

Список атрибутов, которые можно задавать, см. SQLSetConnectAttr. Обратите внимание, что если Attribute указывает атрибут, возвращающий строку, ValuePtr должен быть указателем на буфер для этой строки. Максимальная длина возвращаемой строки, включая символ нулевого завершения, будет байтам BufferLength .

В зависимости от атрибута приложению не обязательно устанавливать соединение перед вызовом SQLGetConnectAttr. Однако если вызывается SQLGetConnectAttr , а указанный атрибут не имеет стандартного значения и не был установлен предыдущим вызовом SQLSetConnectAttr, SQLGetConnectAttr вернёт SQL_NO_DATA.

Если Attribute SQL_ATTR_ TRACE или SQL_ATTR_ TRACEFILE, ConnectionHandle не обязательно должен быть валидным, и SQLGetConnectAttr не возвращает SQL_ERROR или SQL_INVALID_HANDLE, если ConnectionHandle недействителен. Эти атрибуты применимы ко всем связям. SQLGetConnectAttr вернёт SQL_ERROR или SQL_INVALID_HANDLE, если другой аргумент неверен.

Хотя приложение может устанавливать атрибуты операторов с помощью SQLSetConnectAttr, оно не может использовать SQLGetConnectAttr для получения значений атрибутов операторов; он должен вызвать SQLGetStmtAttr для получения настройки атрибутов операторов.

Оба атрибута соединения SQL_ATTR_AUTO_IPD и SQL_ATTR_CONNECTION_DEAD могут быть возвращены вызовом SQLGetConnectAttr , но не могут быть зададены вызовом SQLSetConnectAttr.

Замечание

Асинхронная поддержка SQLGetConnectAttr отсутствует. При реализации SQLGetConnectAttr драйвер может повысить производительность, минимизируя количество отправок или запроса информации с сервера.

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

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-08-24