Функция SQLInstallTranslatorEx

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

Сводка
SQLInstallTranslatorEx добавляет сведения о переводчике в раздел Odbcinst.ini системной информации (HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST. Раздел реестра INI\ODBC Translators).

К функциям SQLInstallTranslatorEx также можно получить доступ с помощью ODBCCONF.EXE.

Синтаксис

  
BOOL SQLInstallTranslatorEx(  
     LPCSTR    lpszTranslator,  
     LPCSTR    lpszPathIn,  
     LPSTR     lpszPathOut,  
     WORD      cbPathOutMax,  
     WORD *    pcbPathOut,  
     WORD      fRequest,  
     LPDWORD   lpdwUsageCount);  

Аргументы

lpszTranslator
[Входные данные] Это должно содержать вдвойне завершенный список пар "ключевое слово-значение", описывающих переводчик. Дополнительные сведения о синтаксисе пары "ключевое слово-значение" см. в подразделах спецификации Переводчика.

Ключевые слова Переводчика и установки должны быть включены в строку lpszTranslator . Библиотека DLL перевода указана с ключевым словом "Переводчик", а библиотека DLL установки переводчика указана с ключевым словом "Настройка ". Каждая пара завершается байтом NULL, и весь список завершается байтом NULL. (То есть два байта NULL помечают конец списка.) Формат lpszTranslator выглядит следующим образом:

\0Translator=translator-DLL-filename\0[Setup=setup-DLL-filename\0]\0

lpszPathIn
[Входные данные] Полный путь к месту установки переводчика или указателя null. Если lpszPath является пустым указателем, переводчики будут установлены в системном каталоге.

lpszPathOut
[Выходные данные] Путь к целевому каталогу, в котором должен быть установлен переводчик. Если переводчик никогда не установлен, lpszPathOut совпадает с lpszPathIn. Если существует предварительная установка переводчика, lpszPathOut — это путь к предыдущей установке.

cbPathOutMax
[Входные данные] Длина lpszPathOut.

pcbPathOut
[Выходные данные] Общее количество байтов, доступных для возврата в lpszPathOut. Если число байтов, доступных для возврата, больше или равно cbPathOutMax, выходной путь в lpszPathOut усечен до pcbPathOutMax минус символ завершения null. Аргумент pcbPathOut может быть указателем null.

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

ODBC_INSTALL_INQUIRY. Запрос о том, где можно установить переводчик.

ODBC_INSTALL_COMPLETE. Выполните запрос на установку.

lpdwUsageCount
[Выходные данные] Количество использования переводчика после вызова этой функции.

Приложения не должны задавать количество использования. ODBC будет поддерживать это число.

Возвраты

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

Диагностика

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

*pfErrorCode	Error	Description
ODBC_ERROR_GENERAL_ERR	Общая ошибка установщика	Произошла ошибка, для которой не было определенной ошибки установщика.
ODBC_ERROR_INVALID_BUFF_LEN	Недопустимая длина буфера	Аргумент lpszPathOut был недостаточно большим, чтобы содержать выходной путь. Буфер содержит усеченный путь. Аргумент cbPathOutMax был 0, и аргумент fRequest был ODBC_INSTALL_COMPLETE.
ODBC_ERROR_INVALID_REQUEST_TYPE	Недопустимый тип запроса	Аргумент fRequest не был одним из следующих: ODBC_INSTALL_INQUIRY ODBC_INSTALL_COMPLETE
ODBC_ERROR_INVALID_KEYWORD_VALUE	Недопустимые пары "ключевое слово-значение"	Аргумент lpszTranslator содержал синтаксическую ошибку.
ODBC_ERROR_INVALID_PATH	Недопустимый путь установки	Аргумент lpszPathIn содержал недопустимый путь.
ODBC_ERROR_INVALID_PARAM_SEQUENCE	Недопустимая последовательность параметров	Аргумент lpszTranslator не содержал список пар "ключевое слово-значение".
ODBC_ERROR_USAGE_UPDATE_FAILED	Не удалось увеличивать или уменьшать количество использования компонентов реестра	Установщик не смог увеличить количество использования переводчика.

Комментарии

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

SQLInstallTranslatorEx увеличивает число использования компонентов для установленного переводчика на 1. Если версия переводчика уже существует, но число использования компонентов для переводчика не существует, то для нового значения количества использования компонентов установлено значение 2.

Программа установки приложений отвечает за физическое копирование файла переводчика и поддержание количества использования файлов. Если файл переводчика ранее не был установлен, программа установки приложения должна скопировать файл или файлы и создать количество использования файлов или файлов. Если файл был установлен ранее, программа установки просто увеличивает количество использования файлов.

Если более ранняя версия переводчика ранее была установлена приложением, переводчик должен быть удален и переустановлен таким образом, чтобы число использования компонентов переводчика было допустимым. SqlRemoveTranslator должен вызываться для уменьшения количества использования компонентов, а затем вызывать SQLInstallTranslatorEx, чтобы увеличить число использования компонентов. Программа установки приложения должна заменить старый файл или файлы новым файлом. Число использования файлов останется прежним, а другие приложения, которые использовали старый файл версии, теперь будут использовать более новую версию.

Длина пути в lpszPathOut в SQLInstallTranslatorEx позволяет выполнять двухфазный процесс установки, поэтому приложение может определить, какой cbPathOutMax должен быть путем вызова SQLInstallTranslatorEx с fRequestst of ODBC_INSTALL_INQUIRY mode. При этом будет возвращено общее количество байтов, доступных в буфере pcbPathOut . Затем SQLInstallTranslatorEx можно вызвать с помощью fRequest ODBC_INSTALL_COMPLETE и аргумента cbPathOutMax , заданного значением в буфере pcbPathOut, а также символом завершения null.

Если вы решили не использовать двухфазную модель для SQLInstallTranslatorEx, необходимо задать cbPathOutMax, которая определяет размер хранилища для пути целевого каталога, значение _MAX_PATH, как определено в Stdlib.h, чтобы предотвратить усечение.

Если fRequest ODBC_INSTALL_COMPLETE, SQLInstallTranslatorEx не позволяет lpszPathOut иметь значение NULL (или cbPathOutMax равным 0). Если fRequest ODBC_INSTALL_COMPLETE, значение FALSE возвращается, если число байтов, доступное для возврата, больше или равно cbPathOutMax, с результатом усечения.

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

Сведения	Раздел
Возврат параметра перевода по умолчанию	ConfigTranslator
Выбор переводчиков	SQLGetTranslator
Удаление переводчиков	SQLRemoveTranslator