SQLInstallTranslatorEx

Conformance

Version Introduced: ODBC 3.0

Summary

SQLInstallTranslatorEx adds information about a translator to the ODBCINST.INI section of the system information.

Syntax

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

Arguments

lpszTranslator

[Input]
This must contain a list of keyword-value pairs describing the translator. The Translator and Setup keywords have to be included in the lpszTranslator string. The translation DLL is listed with the Translator keyword, and the translator setup DLL is listed with the Setup keyword. Each pair is terminated with a NULL byte, and the entire list is terminated with a NULL byte (that is, two NULL bytes mark the end of the list). The format of lpszTranslator is:

translator-desc

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

lpszPathIn

[Input]
Full path of where the translator is to be installed or a null pointer. If lpszPath is a null pointer, then the translators will be installed in the System directory.

lpszPathOut

[Output]
The path of the target directory where the translator should be installed. If the translator has never been installed, then lpszPathOut is the same as lpszPathIn. If there exists a prior installation of the translator, then lpszPathOut is the path of the prior installation.

cbPathOutMax

[Input]
Length of lpszPathOut.

pcbPathOut

[Output]
Total number of bytes available to return in lpszPathOut. If the number of bytes available to return is greater than or equal to cbPathOutMax, the output path in lpszPathOut is truncated to pcbPathOutMax minus the null-termination character. The pcbPathOut argument can be a null pointer.

fRequest

[Input]
Type of request. fRequest must contain one of the following values:

ODBC_INSTALL_INQUIRY: Inquire about where a translator can be installed.

ODBC_INSTALL_COMPLETE: Complete the installation request.

lpdwUsageCount

[Output]
The usage count of the translator after this function has been called.

Returns

The function returns TRUE if it is successful, FALSE if it fails.

Diagnostics

When SQLInstallTranslatorEx returns FALSE, an associated *pfErrorCode value may be obtained by calling SQLInstallerError. The following table lists the *pfErrorCode values that can be returned by SQLInstallerError and explains each one in the context of this function.

Comments

SQLInstallTranslatorEx provides a mechanism to install just the translator. This function does not actually copy any files. The calling program is responsible for copying the translator files.

SQLInstallTranslatorEx increments the component usage count for the installed translator by 1. If a version of the translator already exists, but the component usage count for the translator does not exist, the new component usage count value is set to 2.

The application setup program is responsible for physically copying the translator file, and maintaining the file usage count. If the translator file has not previously been installed, the application setup program must copy the file or files, and create the file or files usage count. If the file has previously been installed, the setup program simply increments the file usage count.

If an older version of the translator was previously installed by the application, the translator should be uninstalled, then reinstalled, so that the translator component usage count is valid. SQLRemoveTranslator should be called to decrement the component usage count, and then SQLInstallTranslatorEx should then be called to increment the component usage count. The application setup program must physically replace the old file or files with the new file. The file usage count will remain the same, and other applications that used the older version file will now use the newer version.

The length of the path in lpszPathOut in SQLInstallTranslatorEx allows for a two-phase install process, so an application can determine what cbPathOutMax should be by calling SQLInstallTranslatorEx with an fRequest of ODBC_INSTALL_INQUIRY mode. This will return the total number of bytes available in the pcbPathOut buffer. SQLInstallTranslatorEx can then be called with an fRequest of ODBC_INSTALL_COMPLETE and the cbPathOutMax argument set to the value in the pcbPathOut buffer, plus the null-termination character.

If you choose not to use the two-phase model for SQLInstallTranslatorEx, then you must set cbPathOutMax, which defines the size of the storage for the path of the target directory, to the value _MAX_PATH, as defined in STDLIB.H, to prevent truncation.

When fRequest is ODBC_INSTALL_COMPLETE, SQLInstallTranslatorEx does not allow lpszPathOut to be NULL (or cbPathOutMax to be 0). If fRequest is ODBC_INSTALL_COMPLETE, FALSE is returned when the number of bytes available to return is greater than or equal to cbPathOutMax, with the result that truncation occurs.

Related Functions