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