MDAC 2.5 SDK - ODBC Programmer's Reference
Chapter 23: Installer DLL API Reference

SQLInstallDriverEx

Conformance

Version Introduced: ODBC 3.0

Summary

SQLInstallDriverEx adds information about the driver to the Odbcinst.ini entry in the system information and increments the driver's UsageCount by 1. However, if a version of the driver already exists but the UsageCount value for the driver does not exist, the new UsageCount value is set to 2.

This function does not actually copy any files. It is the responsibility of the calling program to copy the driver's files to the target directory properly.

Syntax

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

Arguments

lpszDriver

[Input]
The driver description (usually the name of the associated DBMS) presented to users instead of the physical driver name. The lpszDriver argument must contain a list of keyword-value pairs describing the driver.

For more information, see "Comments."

lpszPathIn

[Input]
Full path of the target directory of the installation, or a null pointer. If lpszPathIn is a null pointer, the drivers will be installed in the system directory.

lpszPathOut

[Output]
Path of the target directory where the driver should be installed. If the driver has not previously been installed, lpszPathOut should be the same as lpszPathIn. If the driver was previously installed, lpszPathOut is the path of the previous installation.

cbPathOutMax

[Input]
Length of lpszPathOut.

pcbPathOut

[Output]
Total number of bytes (excluding the null-termination character) 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 cbPathOutMax minus the null-termination character. The pcbPathOut argument can be a null pointer.

fRequest

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

ODBC_INSTALL_INQUIRY: Inquire about where a driver can be installed.

ODBC_INSTALL_COMPLETE: Complete the installation request.

lpdwUsageCount

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

Returns

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

Diagnostics

When SQLInstallDriverEx returns FALSE, an associated *pfErrorCode value can 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

The lpszDriver argument is a list of attributes in the form of keyword-value pairs. 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 this list is as follows:

driver-desc\0Driver=driver-DLL-filename\0[Setup=setup-DLL-filename\0]

   [driver-attr-keyword1=value1\0][driver-attr-keyword2=value2\0]...\0

where \0 is a null byte and driver-attr-keywordn is any driver attribute keyword described in "Driver Keyword Sections" in Chapter 18, "Installing ODBC Components." The keywords must appear in the specified order. For example, suppose a driver for formatted text files has separate driver and setup DLLs and can use files with the .txt and .csv extensions. The lpszDriver argument for this driver might be as follows:

Text\0Driver=TEXT.DLL\0Setup=TXTSETUP.DLL\0FileUsage=1\0
FileExtns=*.txt,*.csv\0\0

Suppose that a driver for SQL Server does not have a separate setup DLL and does not have any driver attribute keywords. The lpszDriver argument for this driver might be as follows:

SQL Server\0Driver=SQLSRVR.DLL\0\0

After SQLInstallDriverEx retrieves information about the driver from the lpszDriver argument, it adds the driver description to the [ODBC Drivers] section of the Odbcinst.ini entry in the system information. It then creates a section titled with the driver's description and adds the full paths of the driver DLL and the setup DLL. Finally, it returns the path of the target directory of the installation but does not copy the driver files to it. The calling program must actually copy the driver files to the target directory.

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

The application setup program is responsible for physically copying the driver file and maintaining the file usage count. If the driver file has not previously been installed, the application setup program must copy the file in the lpszPathIn path and create the file usage count. If the file has previously been installed, the setup program merely increments the file usage count and returns the path of the prior installation in the lpszPathOut argument.

Note   For more information about component usage counts and file usage counts, see "Usage Counting" in Chapter 18, "Installing ODBC Components."

If an older version of the driver file was previously installed by the application, the driver should be uninstalled and then reinstalled, so that the driver component usage count is valid. SQLConfigDriver (with an fRequest of ODBC_REMOVE_DRIVER) should first be called, and then SQLRemoveDriver should be called to decrement the component usage count. SQLInstallDriverEx should then be called to reinstall the driver, incrementing the component usage count. The application setup program must replace the old file with the new file. The file usage count will remain the same, and any other application that used the older version file will now use the newer version.

Note   If the driver was previously installed and SQLInstallDriverEx is called to install the driver in a different directory, the function will return TRUE, but lpszPathOut will include the directory where the driver was already installed. It will not include the directory entered in the lpszDriver argument.

The length of the path in lpszPathOut in SQLInstallDriverEx allows for a two-phase install process, so an application can determine what cbPathOutMax should be by calling SQLInstallDriverEx with an fRequest of ODBC_INSTALL_INQUIRY mode. This will return the total number of bytes available in the pcbPathOut buffer. SQLInstallDriverEx 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 SQLInstallDriverEx, 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, SQLInstallDriverEx 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.

After SQLInstallDriverEx has been called and the application setup program has copied the driver file (if necessary), the driver setup DLL must call SQLConfigDriver to set the configuration for the driver.

Related Functions