Функция SQLDataSources

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

Сводка
SQLDataSources возвращает сведения о источнике данных. Эта функция реализуется только диспетчером драйверов.

Синтаксис

  
SQLRETURN SQLDataSources(  
     SQLHENV          EnvironmentHandle,  
     SQLUSMALLINT     Direction,  
     SQLCHAR *        ServerName,  
     SQLSMALLINT      BufferLength1,  
     SQLSMALLINT *    NameLength1Ptr,  
     SQLCHAR *        Description,  
     SQLSMALLINT      BufferLength2,  
     SQLSMALLINT *    NameLength2Ptr);  

Аргументы

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

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

SQL_FETCH_NEXT (чтобы получить следующее имя источника данных в списке), SQL_FETCH_FIRST (для получения с начала списка), SQL_FETCH_FIRST_USER (для получения первого имени пользователя DSN) или SQL_FETCH_FIRST_SYSTEM (для получения первого имени пользователя DSN).

Если для параметра "Направление" задано значение SQL_FETCH_FIRST, последующие вызовы SQLDataSources с параметром "Направление" SQL_FETCH_NEXT возвращают как пользовательские, так и системные DSN. Если для параметра "Направление" задано значение SQL_FETCH_FIRST_USER, все последующие вызовы SQLDataSources с параметром "Направление" SQL_FETCH_NEXT возвращают только пользовательские доменные имена. Если для параметра "Направление" задано значение SQL_FETCH_FIRST_SYSTEM, все последующие вызовы SQLDataSources с параметром "Направление" SQL_FETCH_NEXT возвращают только системные доменные сети.

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

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

BufferLength1
[Входные данные] Длина буфера *ServerName в символах; это не должно быть больше, чем SQL_MAX_DSN_LENGTH плюс символ завершения null.

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

Описание
[Выходные данные] Указатель на буфер, в котором возвращается описание драйвера, связанного с источником данных. Например, dBASE или SQL Server.

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

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

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

Возвраты

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

Диагностика

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

Комментарии

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

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

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

Драйвер определяет, как имена источников данных сопоставляются с фактическими источниками данных.

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

См. также

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