The following specification of SQLInstallDriverEx is from the Microsoft ODBC SDK Reference.
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.BOOL SQLInstallDriverEx( LPCSTR lpszDriver, LPCSTR lpszPathIn, LPSTR lpszPathOut, WORD cbPathOutMax, WORD * pcbPathOut, WORD fRequest, LPDWORD lpdwUsageCount);
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.
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.
Path of the target directory where the driver should be installed. If the driver has not previously been installed then lpszPathOut should be the same as lpszPathIn. If the driver was previously installed then lpszPathOut is the path of the previous installation.
Length of lpszPathOut.
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 then the output path in lpszPathOut is truncated to cbPathOutMax minus the null-termination character. The pcbPathOut argument can be a null pointer.
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.
The usage count of the driver after this function has been called.
The function returns TRUE if it is successful, FALSE if it fails.
When SQLInstallDriverEx 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.
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:
where \0 is a null byte and driver-attr-keywordn is any driver attribute keyword described in the table that follows:
These sections should not include the Driver keyword, since this is specified in the driver specification section, but must include enough information for the ConfigDSN function in the driver setup DLL to create a remote data source specification without displaying any dialog boxes. For the format of a data source specification section, see Remote Database Parameters.
A three-character string indicating whether the driver supports SQLConnect, SQLDriverConnect, and SQLBrowseConnect.
A number indicating how a file-based driver directly treats files in a data source.
0 = The driver is not a file-based driver. For example, a Mimer SQL driver is a DBMS-based driver.
1 = A file-based driver treats files in a data source as tables. For example, an Xbase driver treats each Xbase file as a table.
2 = A file-based driver treats files in a data source as a catalog. For example, a Microsoft Access driver treats each Microsoft Access file as a complete database.
The keywords must appear in the specified order.
Mimer SQL Example
A typical Mimer SQL value for this argument is the following string (new lines added for readability):MIMER\0 Driver=Mimodb32.dll\0 Setup=Mimset32.dll\0 SQLLevel=1\0 FileUsage=0\0 DriverODBCVer=03.51\0 ConnectFunctions=YYY\0 APILevel=2\0 CPTimeout=60\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.
If an older version of the driver file was previously installed by the application, the driver should be uninstalled, then reinstalled, so that the driver component usage count is valid. SQLConfigDriver (with an fRequest of ODBC_REMOVE_DRIVER) should first be called, 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 physically 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 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, 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.
Upright Database Technology AB
Voice: +46 18 780 92 00
Fax: +46 18 780 92 40