Функция 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 |