Функция SQLGetConnectAttr

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

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

Заметка

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

Синтаксис

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

Аргументы

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

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

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

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

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

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

• Если *ValuePtr является указателем на символьную строку, BufferLength — это длина строки.

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

• Если значение *ValuePtr является указателем на значение, отличное от символьной строки или двоичной строки, BufferLength должно иметь значение SQL_IS_POINTER.

• Если параметр *ValuePtr содержит тип данных фиксированной длины, БуферLength либо SQL_IS_INTEGER, либо SQL_IS_UINTEGER, как это необходимо.

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

Возвраты

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

Диагностика

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

SQLSTATE	Error	Description
01000	Общее предупреждение	Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
01004	Строковые данные, усеченные справа	Данные, возвращаемые в *ValuePtr , были усечены для буфераLength минус длина символа завершения null. Длина ненадежного строкового значения возвращается в *StringLengthPtr. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
08003	Подключение не открыто	(DM) Значение атрибута , требующее открытого подключения.
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	Недопустимый идентификатор атрибута или параметра	Значение, указанное для атрибута аргумента, недопустимо для версии ODBC, поддерживаемой драйвером.
HY114	Драйвер не поддерживает асинхронное выполнение асинхронной функции на уровне подключения	(DM) Приложение попыталось включить асинхронное выполнение функции с SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE для драйвера, который не поддерживает асинхронные операции подключения.
HY117	Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения.	(DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function.
HYC00	Необязательный компонент не реализован	Значение, указанное для атрибута аргумента, является допустимым атрибутом подключения ODBC для версии ODBC, поддерживаемой драйвером, но не поддерживается драйвером.
HYT01	Время ожидания для подключения истекло	Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Драйвер не поддерживает эту функцию	(DM) Драйвер, соответствующий ConnectionHandle , не поддерживает функцию.

Комментарии

Общие сведения об атрибутах подключения см. в разделе "Атрибуты подключения".

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

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

Если атрибут 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

См. также

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