Функция ConfigDSN

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

Сводка
ConfigDSN добавляет, изменяет или удаляет источники данных из системной информации. Он может запрашивать у пользователя сведения о подключении. Он может находиться в библиотеке DLL драйвера или отдельной библиотеке установки.

Синтаксис

  
BOOL ConfigDSN(  
     HWND     hwndParent,  
     WORD     fRequest,  
     LPCSTR   lpszDriver,  
     LPCSTR   lpszAttributes);  

Аргументы

hwndParent
[Входные данные] Родительский дескриптор окна. Функция не будет отображать диалоговые окна, если дескриптор имеет значение NULL.

fRequest
[Входные данные] Тип запроса. Аргумент fRequest должен содержать одно из следующих значений:

ODBC_ADD_DSN. Добавление нового источника данных.

ODBC_CONFIG_DSN. Настройка (изменение) существующего источника данных.

ODBC_REMOVE_DSN. Удаление существующего источника данных.

lpszDriver
[Входные данные] Описание драйвера (обычно имя связанной СУБД), представленное пользователям вместо имени физического драйвера.

lpszAttributes
[Входные данные] Двукратный список атрибутов, завершаемых значением NULL, в виде пар "ключевое слово-значение". Дополнительные сведения см. в разделе "Комментарии".

Возвраты

Функция возвращает значение TRUE, если оно выполнено успешно, значение FALSE, если оно завершается ошибкой.

Диагностика

Когда ConfigDSN возвращает значение FALSE, связанное значение *pfErrorCode помещается в буфер ошибок установщика вызовом SQLPostInstallerError и может быть получено путем вызова SQLInstallerError. В следующей таблице перечислены значения *pfErrorCode , которые можно возвращать SQLInstallerError и объясняет каждый из них в контексте этой функции.

*pfErrorCode	Error	Description
ODBC_ERROR_INVALID_HWND	Недопустимый дескриптор окна	Недопустимый аргумент hwndParent .
ODBC_ERROR_INVALID_KEYWORD_VALUE	Недопустимые пары "ключевое слово-значение"	Аргумент lpszAttributes содержит синтаксическую ошибку.
ODBC_ERROR_INVALID_NAME	Недопустимое имя драйвера или переводчика	Недопустимый аргумент lpszDriver . Его не удалось найти в реестре.
ODBC_ERROR_INVALID_REQUEST_TYPE	Недопустимый тип запроса	Аргумент fRequest не был одним из следующих: ODBC_ADD_DSN ODBC_CONFIG_DSN ODBC_REMOVE_DSN
ODBC_ERROR_REQUEST_FAILED	Сбой запроса	Не удалось выполнить операцию, запрошенную аргументом fRequest .
ODBC_ERROR_DRIVER_SPECIFIC	Ошибка драйвера или переводчика	Ошибка для конкретного драйвера, для которой не определена ошибка установщика ODBC. Аргумент SzError в вызове функции SQLPostInstallerError должен содержать сообщение об ошибке для конкретного драйвера.

Комментарии

ConfigDSN получает сведения о подключении из библиотеки DLL установщика в виде списков атрибутов в виде пар "ключевое слово-значение". Каждая пара завершается с байтом NULL, и весь список завершается с байтом NULL. (То есть два байта null помечают конец списка.) Пробелы не допускаются вокруг равного знака в паре "ключевое слово-значение". ConfigDSN может принимать ключевые слова, которые являются недопустимыми ключевыми словами для SQLBrowseConnect и SQLDriverConnect. ConfigDSN не обязательно поддерживает все ключевые слова, которые являются допустимыми ключевыми словами для SQLBrowseConnect и SQLDriverConnect. (ConfigDSN не принимает ключевое слово DRIVER .) Ключевые слова, используемые функцией ConfigDSN , должны поддерживать все параметры, необходимые для повторного создания источника данных с помощью функции настройки AUTO установщика. Если используются значения ConfigDSN и значения строки подключения одинаковы, следует использовать те же ключевые слова.

Как и в SQLBrowseConnect и SQLDriverConnect, ключевые слова и их значения не должны содержать []{}(),?? *=!@ символы, а значение ключевого слова DSN не может состоять только из пустых. Из-за грамматики реестра ключевые слова и имена источников данных не могут содержать символ обратной косой черты (\).

ConfigDSN должен вызывать SQLValidDSN, чтобы проверить длину имени источника данных и убедиться, что недопустимые символы не включены в имя. Если имя источника данных больше SQL_MAX_DSN_LENGTH или содержит недопустимые символы, SQLValidDSN возвращает ошибку, а ConfigDSN возвращает ошибку. Длина имени источника данных также проверяется SQLWriteDSNToIni.

Например, чтобы настроить источник данных, требующий идентификатор пользователя, пароль и имя базы данных, приложение установки может передать следующие пары "ключевое слово-значение":

DSN=Personnel Data\0UID=Smith\0PWD=Sesame\0DATABASE=Personnel\0\0  

Дополнительные сведения об этих ключевых словах см . в документации по SQLDriverConnect и каждому драйверу.

Чтобы отобразить диалоговое окно, hwndParent не должно иметь значение NULL.

Добавление источника данных

Если имя источника данных передается в ConfigDSN в lpszAttributes, ConfigDSN проверяет, является ли имя допустимым. Если имя источника данных соответствует существующему имени источника данных и hwndParent равно NULL, ConfigDSN перезаписывает существующее имя. Если оно соответствует существующему имени и hwndParent не равно null, ConfigDSN предложит пользователю перезаписать существующее имя.

Если lpszAttributes содержит достаточно сведений для подключения к источнику данных, ConfigDSN может добавить источник данных или отобразить диалоговое окно, с помощью которого пользователь может изменить сведения о подключении. Если lpszAttributes не содержит достаточно сведений для подключения к источнику данных, ConfigDSN должен определить необходимые сведения; если hwndParent не имеет значения NULL, он отображает диалоговое окно для получения сведений от пользователя.

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

Если ConfigDSN не может получить полные сведения о подключении для источника данных, возвращает значение FALSE.

Если ConfigDSN может получить полные сведения о подключении к источнику данных, он вызывает SQLWriteDSNToIni в библиотеке DLL установщика, чтобы добавить новую спецификацию источника данных в файл Odbc.ini (или реестр). SQLWriteDSNToIni добавляет имя источника данных в раздел [Источники данных ODBC], создает раздел спецификации источника данных и добавляет ключевое слово DRIVER с описанием драйвера в качестве значения. ConfigDSN вызывает SQLWritePrivateProfileString в библиотеке DLL установщика, чтобы добавить любые дополнительные ключевые слова и значения, используемые драйвером.

Изменение источника данных

Чтобы изменить источник данных, необходимо передать имя источника данных в ConfigDSN в lpszAttributes. ConfigDSN проверяет, находится ли имя источника данных в файле Odbc.ini (или реестре).

Если hwndParent имеет значение NULL, ConfigDSN использует сведения в lpszAttributes для изменения сведений в файле Odbc.ini (или реестре). Если hwndParent не является null, ConfigDSN отображает диалоговое окно с помощью сведений в lpszAttributes; для информации, не в lpszAttributes, она использует сведения из системных сведений. Пользователь может изменить сведения, прежде чем ConfigDSN сохраняет его в системной информации.

Если имя источника данных было изменено, ConfigDSN сначала вызывает SQLRemoveDSNFromIni в библиотеке DLL установщика, чтобы удалить существующую спецификацию источника данных из файла Odbc.ini (или реестра). Затем он выполняет действия, описанные в предыдущем разделе, чтобы добавить новую спецификацию источника данных. Если имя источника данных не было изменено, ConfigDSN вызывает SQLWritePrivateProfileString в библиотеке DLL установщика, чтобы внести другие изменения. ConfigDSN может не удалять или изменять значение ключевого слова Driver .

Удаление источника данных

Чтобы удалить источник данных, необходимо передать имя источника данных в ConfigDSN в lpszAttributes. ConfigDSN проверяет, находится ли имя источника данных в файле Odbc.ini (или реестре). Затем он вызывает SQLRemoveDSNFromIni в библиотеке DLL установщика, чтобы удалить источник данных.

Заметка

При написании версии юникода этой подпрограммы необходимо вызвать ConfigDSNW с аргументами LPCWSTR вместо LPCSTR.

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

Сведения	Раздел
Добавление, изменение или удаление источника данных	SQLConfigDataSource
Получение значения из файла Odbc.ini или реестра	SQLGetPrivateProfileString
Удаление источника данных по умолчанию	SQLRemoveDefaultDataSource
Удаление имени источника данных из Odbc.ini (или реестра)	SQLRemoveDSNFromIni
Добавление имени источника данных в Odbc.ini (или реестр)	SQLWriteDSNToIni
Запись значения в файл Odbc.ini или реестр	SQLWritePrivateProfileString