Функция SQLDrivers

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

Сводка
В SQLDrivers перечислены описания драйверов и ключевые слова атрибутов драйвера. Эта функция реализуется только диспетчером драйверов.

Синтаксис

  
SQLRETURN SQLDrivers(  
     SQLHENV         EnvironmentHandle,  
     SQLUSMALLINT    Direction,  
     SQLCHAR *       DriverDescription,  
     SQLSMALLINT     BufferLength1,  
     SQLSMALLINT *   DescriptionLengthPtr,  
     SQLCHAR *       DriverAttributes,  
     SQLSMALLINT     BufferLength2,  
     SQLSMALLINT *   AttributesLengthPtr);  

Аргументы

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

Направление
[Входные данные] Определяет, извлекает ли диспетчер драйверов следующее описание драйвера в списке (SQL_FETCH_NEXT) или начинается ли поиск с начала списка (SQL_FETCH_FIRST).

DriverDescription
[Выходные данные] Указатель на буфер, в котором возвращается описание драйвера.

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

BufferLength1
[Входные данные] Длина буфера *DriverDescription в символах.

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

DriverAttributes
[Выходные данные] Указатель на буфер, в котором возвращаются пары значений атрибута драйвера (см. раздел "Примечания").

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

BufferLength2
[Входные данные] Длина буфера *DriverAttributes в символах. Если значение *DriverDescription является строкой Юникода (при вызове SQLDriversW), аргумент BufferLength должен быть четным.

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

Возвраты

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

Диагностика

При возврате sqlDrivers SQL_ERROR или SQL_SUCCESS_WITH_INFO связанное значение SQLSTATE можно получить путем вызова SQLGetDiagRec с помощью HandleType SQL_HANDLE_ENV и Handle of EnvironmentHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLDrivers и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.

SQLSTATE	Error	Description
01000	Общее предупреждение	Информационное сообщение диспетчера драйверов (DM). (Функция возвращает SQL_SUCCESS_WITH_INFO.)
01004	Строковые данные, усеченные справа	(DM) Буфер *DriverDescription был недостаточно велик, чтобы вернуть полное описание драйвера. Поэтому описание было усечено. Длина полного описания драйвера возвращается в *DescriptionLengthPtr. (Функция возвращает SQL_SUCCESS_WITH_INFO.) (DM) Буфер *DriverAttributes был недостаточно большим, чтобы вернуть полный список пар значений атрибута. Поэтому список был усечен. Длина ненадежного списка пар значений атрибута возвращается в *AttributesLengthPtr. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
HY000	Общая ошибка	Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину.
HY001	Ошибка выделения памяти	(DM) Диспетчер драйверов не смог выделить память, необходимую для поддержки выполнения или завершения функции.
HY010	Ошибка последовательности функций	(DM) SQLExecute, SQLExecDirect или SQLMoreResults был вызван для ОператораHandle и возвращен SQL_PARAM_DATA_AVAILABLE. Эта функция была вызвана до получения данных для всех потоковых параметров.
HY013	Ошибка управления памятью	Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти.
HY090	Недопустимая длина строки или буфера	(DM) Значение, указанное для аргумента BufferLength1 , было меньше 0. (DM) Значение, указанное для аргумента BufferLength2 , меньше 0 или равно 1.
HY103	Недопустимый код извлечения	(DM) Значение, указанное для направления аргумента, не равно SQL_FETCH_FIRST или SQL_FETCH_NEXT.
HY117	Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения.	(DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function.

Комментарии

SQLDrivers возвращает описание драйвера в буфере *DriverDescription . Он возвращает дополнительные сведения о драйвере в буфере *DriverAttributes в виде списка пар "ключевое слово-значение". Все ключевые слова, перечисленные в системной информации для драйверов, будут возвращены для всех драйверов, за исключением CreateDSN, который используется для запроса на создание источников данных и поэтому является необязательным. Каждая пара завершается с байтом NULL, и полный список завершается с байтом NULL (то есть два байта NULL помечают конец списка). Например, драйвер на основе файлов с использованием синтаксиса C может возвращать следующий список атрибутов ("\0" представляет пустой символ):

FileUsage=1\0FileExtns=*.dbf\0\0  

Если *DriverAttributes недостаточно велик для хранения всего списка, список усечен, SQLDrivers возвращает SQLSTATE 01004 (усечено данные), а длина списка (за исключением окончательного байта завершения null) возвращается в *AttributesLengthPtr.

Ключевые слова атрибута драйвера добавляются из системных сведений при установке драйвера. Дополнительные сведения см. в разделе "Установка компонентов ODBC".

Приложение может вызывать SQLDrivers несколько раз, чтобы получить все описания драйверов. Диспетчер драйверов извлекает эти сведения из системных сведений. Если нет дополнительных описаний драйверов, SQLDrivers возвращает SQL_NO_DATA. Если SQLDrivers вызывается с SQL_FETCH_NEXT сразу после возврата SQL_NO_DATA, он возвращает первое описание драйвера. Сведения о том, как приложение использует сведения, возвращаемые SQLDrivers, см. в разделе "Выбор источника данных" или "Драйвер".

Если SQL_FETCH_NEXT передается в SQLDrivers при первом вызове, SQLDrivers возвращает первое имя источника данных.

Так как SQLDrivers реализован в диспетчере драйверов, он поддерживается для всех драйверов независимо от соответствия определенным стандартам драйвера.

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

Сведения	Раздел
Обнаружение и перечисление значений, необходимых для подключения к источнику данных	Функция SQLBrowseConnect
подключение к источнику данных;	Функция SQLConnect
Возврат имен источников данных	Функция SQLDataSources
Подключение к источнику данных с помощью строки подключения или диалогового окна	Функция SQLDriverConnect

См. также

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