Функция SQLGetConnectAttr

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

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

Синтаксис

  
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, если не указано иное.

Комментарии

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

Список атрибутов, которые можно задать, см. в разделе 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.

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

См. также

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