www.mimer.com/developer

6.3 SQLInstallDriverEx

---

The following specification of SQLInstallDriverEx is from the Microsoft ODBC SDK Reference.

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 then lpszPathOut should be the same as lpszPathIn. If the driver was previously installed then 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 then 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 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.

*pfErrorCode	Error	Description
ODBC_ERROR_ GENERAL_ERR	General installer error	An error occurred for which there was no specific installer error.
ODBC_ERROR_ INVALID_BUFF_LEN	Invalid buffer length	The lpszPathOut argument was not large enough to contain the output path. The buffer contains the truncated path. The cbPathOutMax argument was 0 and fRequest was ODBC_INSTALL_COMPLETE.
ODBC_ERROR_ INVALID_ REQUEST_TYPE	Invalid type of request	The fRequest argument was not one of the following: ODBC_INSTALL_INQUERY ODBC_INSTALL_COMPLETE
ODBC_ERROR_ INVALID_ KEYWORD_VALUE	Invalid keyword-value pairs	The lpszDriver argument contained a syntax error.
ODBC_ERROR_ INVALID_PATH	Invalid install path	The lpszPathIn argument contained an invalid path.
ODBC_ERROR_ LOAD_LIBRARY _FAILED	Could not load the driver or translator setup library	The driver setup library could not be loaded.
ODBC_ERROR_ INVALID_PARAM_ SEQUENCE	Invalid parameter sequence	The lpszDriver argument did not contain a list of keyword value pairs.
ODBC_ERROR_ USAGE_UPDATE_ FAILED	Could not increment or decrement the component usage count	The installer failed to increment the driver's usage count.

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:

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 the table that follows:

Keyword	Usage
APILevel	A number indicating the ODBC interface conformance level supported by the driver: 0 = None 1 = Level 1 supported 2 = Level 2 supported This must be the same as the value returned for the SQL_ODBC_INTERFACE_CONFORMANCE option in SQLGetInfo.
CreateDSN	The name of one or more data sources to be created when the driver is installed. The system information must include one data source specification section for each data source listed with the CreateDSN keyword. 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.
ConnectFunctions	A three-character string indicating whether the driver supports SQLConnect, SQLDriverConnect, and SQLBrowseConnect. If the driver supports SQLConnect, the first character is 'Y'; otherwise, it is 'N'. If the driver supports SQLDriverConnect, the second character is 'Y'; otherwise, it is 'N'. If the driver supports SQLBrowseConnect, the third character is 'Y'; otherwise, it is 'N'. For example, if a driver supports SQLConnect and SQLDriverConnect, but not SQLBrowseConnect, the three-character string is 'YYN'.
DriverODBCVer	A character string with the version of ODBC that the driver supports. The version is of the form nn.nn, where the first two digits are the major version and the next two digits are the minor version. For the version of ODBC described in this manual, the driver must return '03.00'.This must be the same as the value returned for the SQL_DRIVER_ODBC_VER option in SQLGetInfo.
FileExtns	For file-based drivers, a comma-separated list of extensions of the files the driver can use. See the FileUsage keyword below.
FileUsage	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.
SQLLevel	A number indicating the SQL-92 grammar supported by the driver: 0 = SQL-92 Entry 1 = FIPS127-2 Transitional 2 = SQL-92 Intermediate 3 = SQL-92 Full This must be the same as the value returned for the SQL_SQL_CONFORMANCE option in SQLGetInfo.

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=Mimodbcw.dll\0 
Setup=Mimsetw.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.

Mimer Information Technology AB Voice: +46 18 780 92 00 Fax: +46 18 780 92 40 info@mimer.se