Функция SQLCreateDataSource

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

Сводка
SQLCreateDataSource отображает диалоговое окно, с помощью которого пользователь может добавить источник данных.

Синтаксис

  
BOOL SQLCreateDataSource(  
     HWND    hwnd,  
     LPSTR   lpszDS);  

Аргументы

hwnd
[Входные данные] Родительский дескриптор окна.

lpszDS
[Входные данные] Имя источника данных. lpszDS может быть пустым указателем или пустой строкой.

Возвраты

SQLCreateDataSource возвращает значение TRUE, если создается источник данных. В противном случае возвращает значение FALSE.

Диагностика

Когда SQLCreateDataSource возвращает ЗНАЧЕНИЕ FALSE, связанное значение *pfErrorCode можно получить путем вызова SQLInstallerError. В следующей таблице перечислены значения *pfErrorCode , которые можно возвращать SQLInstallerError и объясняет каждый из них в контексте этой функции.

*pfErrorCode	Error	Description
ODBC_ERROR_GENERAL_ERR	Общая ошибка установщика	Произошла ошибка, для которой не было определенной ошибки установщика.
ODBC_ERROR_INVALID_HWND	Недопустимый дескриптор окна	Недопустимый аргумент hwnd или NULL.
ODBC_ERROR_INVALID_DSN	Недопустимая dsN	Аргумент lpszDS содержал строку, недопустимую для имени DSN.
ODBC_ERROR_REQUEST_FAILED	Сбой запроса	Сбой вызова ConfigDSN с параметром ODBC_ADD_DSN.
ODBC_ERROR_LOAD_LIBRARY_FAILED	Не удалось загрузить библиотеку установки драйвера или переводчика	Не удалось загрузить библиотеку установки драйвера.
ODBC_ERROR_USER_CANCELED	Операция отмены пользователем	Пользователь отменил создание нового источника данных.
ODBC_ERROR_CREATE_DSN_FAILED	Не удалось создать запрошенный DSN	Не удалось подключиться к базе данных; Вызов SQLDriverConnect для имени dsN файла не вернул успешное подключение. Не удалось записать в файл.
ODBC_ERROR_OUT_OF_MEM	Недостаточно памяти	Установщик не мог выполнить функцию из-за нехватки памяти.

Комментарии

Если hwnd имеет значение NULL, SQLCreateDataSource возвращает ЗНАЧЕНИЕ FALSE. В противном случае откроется диалоговое окно "Создание источника данных" со страницей мастера для выбора типа источника данных , который необходимо настроить, как показано на следующем рисунке.

Параметром по умолчанию является источник данных файла. После выбора источника данных и нажатия кнопки "Далее " отображается следующая страница мастера, содержащая список установленных драйверов.

Если нажмите кнопку "Отмена ", диалоговое окно исчезает, а SQLCreateDataSource возвращает ЗНАЧЕНИЕ FALSE с кодом ошибки ODBC_ERROR_USER_CANCELED. Если выбран параметр "Источник данных пользователя" или "Системный источник данных", кнопка "Дополнительно" недоступна.

При нажатии кнопки "Далее" будет выполнено одно из следующих действий в зависимости от типа источника данных:

• Если выбран источник данных файлов, отобразится страница мастера, чтобы пользователь ввел имя файла.

• Если выбран источник данных пользователя или системный источник данных, страница мастера, отображающая тип источника данных и драйвера, отображается для проверки, а после нажатия кнопки "Готово" будет настроен источник данных.

Если на странице мастера создания источника данных щелкните "Дополнительно ", отобразится страница мастера для ввода сведений о драйвере. В текстовом поле этого диалогового окна введите драйвер и ключевые слова, разделенные возвращаемыми, как показано на следующем рисунке.

Дополнительные ключевые слова для конкретного драйвера можно найти в описании SQLDriverConnect. Все, кроме DSN , разрешены.

Значение по умолчанию для параметра "Проверить это подключение" имеет значение TRUE. Это по умолчанию применяется, активируется ли эта страница мастера. Если установлен флажок , строка, указанная в текстовом поле, и значение параметра "Проверить это подключение" кэшируется. (Если Кнопка "Закрыть " или "Отмена ", все введенные сведения о драйвере теряются, так как строка, указанная в текстовом поле, и значение параметра "Проверить это подключение " не кэшируется.)

Если на первой странице мастера выбран источник данных файлов, после выбора драйвера и ввода ключевых слов на странице мастера "Дополнительно" пользователю будет предложено ввести имя файла. Нажмите кнопку "Обзор", чтобы найти имя файла, в этом случае каталог по умолчанию в поле обзора указывается сочетанием пути, указанного CommonFileDir в HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion и ODBC\DataSources. (Если CommonFileDir был "C:\Program Files\Common Files", каталог по умолчанию будет "C:\Program Files\Common Files\ODBC\Data Sources".

При вводе имени файла и нажатии кнопки Next имя файла проверяется на допустимость стандартных правил именования файлов операционной системы. Если имя файла недопустимо, поле сообщения об ошибке уведомляет пользователя о том, что введено недопустимое имя файла. После подтверждения поля сообщения фокус возвращается на страницу мастера, в которой вводится имя файла. Если имя файла допустимо, страница мастера с выбранными парами "ключевое слово-значение" отображается для проверки, как показано на следующем рисунке.

Если выбран параметр "Готово " и "Источник данных файлов" был выбран в качестве типа источника данных, а если параметр "Проверить это подключение " имеет значение TRUE, sqlDriverConnect вызывается с ключевыми словами SAVEFILE и DRIVER . Аргумент DriverCompletion имеет значение SQL_DRIVER_COMPLETE. Имя файла ключевого слова SAVEFILE — это имя, введенное или выбранное, а имя драйвера для ключевого слова DRIVER — это имя, которое было выбрано. Если на странице мастера расширенного мастера указана строка подключения для конкретного драйвера, эта строка добавляется после ключевого слова DRIVER .

Если SQLDriverConnect возвращает SQL_SUCCESS, диспетчер драйверов создал dsN файла. SQLCreateDataSource возвращает ЗНАЧЕНИЕ TRUE. Если SQLDriverConnect не возвращает SQL_SUCCESS, поле предупреждения указывает, что подключение к источнику данных не удалось сделать. DsN с минимальными сведениями о подключении по-прежнему можно создать. Это поле сообщения позволяет пользователю отменить или продолжить создание имени dsN файла.

Если пользователь решит продолжить создание dsN, этот процесс продолжается так, как если параметр проверки этого подключения был задан как FALSE. Если пользователь решит отменить, значение FALSE возвращается для SQLCreateDataSource с кодом ошибки ODBC_ERROR_CREATE_DSN_FAILED.

Если в качестве типа источника данных выбран источник данных и параметр "Проверить это подключение " имеет значение FALSE, создается имя DSN файла с ключевым словом DRIVER и указанной пользователем строкой подключения (при наличии) на странице мастера "Дополнительно". Если создание файла выполнено успешно, значение TRUE возвращается для SQLCreateDataSource. Если создание файла не выполнено, сообщение об ошибке уведомляет пользователя о любой ошибке, возвращенной из операционной системы. ЗНАЧЕНИЕ FALSE возвращается для SQLCreateDataSource с кодом ошибки ODBC_ERROR_CREATE_DSN_FAILED. Дополнительные сведения о источниках данных файлов см. в разделе "Подключение с помощью источников данных файлов" или сведения о SQLDriverConnect.

Если в качестве типа источника данных выбран пользователь или системный источник данных, ConfigDSN в библиотеке установки драйвера вызывается с ODBC_ADD_DSN fRequest. Дополнительные сведения см. в разделе ConfigDSN.

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

Сведения	Раздел
Управление источниками данных	SQLManageDataSources