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

Комментарии

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 реализован в диспетчере драйверов, он поддерживается для всех драйверов независимо от соответствия определенным стандартам драйвера.

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

См. также

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