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

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

Комментарии

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

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

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

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

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

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

См. также

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